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PREFACE 


This manual describes the use of the RT-11 Operating System. It 
assumes the reader is familiar with computer software fundamentals and 
has had some exposure to assembly language programs. The section 
"Additional and Reference Material" later in this Preface lists 
documents that may prove helpful in reviewing those areas. The 
Glossary provides definitions of technical terms used in the manual. 

The user who is unfamiliar with RT-11 should first read those chapters 
of interest (see "Chapter Summary" below) to become familiar with 
system conventions. Having gained familiarity with RT-11, the user 
can then reread the manual for specific information. 


Chapter Summary 

Chapter 1 discusses system hardware and software requirements. It 
describes general system operations and lists specific components 
available under RT-11. 

Chapter 2 introduces the user to system conventions and monitor/memory 
layout. It describes in detail the keyboard commands for controlling 
jobs and implementing user programs. 

Chapters 3 through 8 describe the system utility programs EDIT, PIP, 
MACRO, LINK, LIBR, and ODT, respectively. These programs (a text 
editor, file transfer program, assembler, linker, librarian, and 
debugging program) aid the user in creating text files and producing 
assembly-language programs. 

Chapter 9, which describes programmed requests, is of particular 
interest to the experienced programmer. It describes call sequences 
that allow the user to access system monitor services from within 
assembly-language programs. 

Chapters 10 and 11 describe the 8K Assembler and EXPAND programs, 
respectively. These programs are useful in RT-11 installations with 
minimum memory configurations. 

Chapter 12 describes the BATCH command language for RT-11. In BATCH 
mode, the RT-11 system can be left to run unattended for long periods 
of time. 

The appendixes summarize the contents of the manual and describe 
additional system utility programs that can be used for extended 
system operations. These programs include SRCCOM (a source file 
comparison program); FILEX (a file translation program that allows 
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transfer of files between RT-11 and other DIGITAL operating systems); 
PATCH and PATCHO (patching programs); DUMP (a file dump program); 
and SYSLIB (a library of programmed requests for FORTRAN users). 


Version History 

The current RT-11 system (monitor) is Version 2C (V2C). Each system 
component (monitors and utilities) is assigned a software 
identification number in the form Vxx-xx. Current identification 
numbers for V2C are listed in the RT-11 System Release Notes 
(DEC-ll-CRNRA-A-D). To determine whether the correct version of a 
component is in use, examine its identification number and compare it 
with the list. (The procedure for examining the version number 
varies. Most system programs provide a special command; others print 
the version number when an output listing is requested. Consult the 
approiate chapter or appendix of this manual for each component.) 


NOTE 


Throughout this manual, any references 
to V2 or V2B of RT-11 will pertain also 
to V2C. The RT-11 System Release Notes 
contain a comprehensive list of 
differences between V2C and previous 
versions of RT-11 (V2B, V2, VI). 


Change bars and asterisks in the outermost margins of the manual are 
used to denote changes made to the text since the Version 2 release 
(DEC-11-ORUGA-B-D). The date July 1975 in the lower outside corner of 
a page indicates that the page was changed as a result of a 
release-independent update that occurred in July, 1975. The date 
January 1976 in the lower outside corner of the page indicates that 
the page was changed specifically as a result of the V2C update. 


The user who is already familiar with the Version 2B RT-11 System 
Reference Manual (DEC-11-0RUGA-C-D,DNl) should first read the RT-11 
System Release Notes document to note the major differences between 
V2B and V2C, and then read those pages of the RT-11 System Reference 
Manual that have changed as a result of the V2C update (identified by 
the date January 1976). The RT-11 System Generation Manual 
(DEC-11-0RGMA-A-D) should also be read if customization for special 
devices and features is required. 


The user who is familiar with only the Version 2 RT-11 System 
Reference Manual (DEC-11-0RUGA-B-D) should read the following in 
addition to those items mentioned in the preceding paragraph: 


Chapter 2 
Chapter 3 
Chapter 9 
Chapter 12 
Appendix H 

Appendix 0 


(System Communication) - Tables 2-2, 2-3, and 2-5 

(Text Editor) - Section 3.6.5.6 

(Programmed Requests) - Sections 9.1 and 9.1.3.6 

(BATCH) - Entire Chapter 

(F/B Programming 

And Device Handlers) - Sections H.2.4 and H.2.5 

(SYSLIB) - Entire Appendix 


Finally, the user familiar with only 
Reference Manual (DEC-11-0RUGA-A-D) 
with these exceptions: 


the Version 1 RT-11 System 

should read this entire manual 
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Chapter 

Chapter 

Chapter 


3 (Text Editor) 

5 (MACRO Assembler) 
8 (ODT) 


Chapter 10 (EXPAND) 
Chapter 11 (ASEMBL) 
Appendix L (PATCH) 


note Section 3.7 
note Section 5.7 
note restrictions in Section 
8.1 


While knowledge of Versions 2 and 2B is sufficient for use of V2C 
knowledge of Version 1 is not; the user with Version 1 knowledge only 
should carefully read the manual. 


Additional and Reference Material 

The following manuals provide an introduction to the PDP-11 computer 
family and the basic PDP-11 instruction set: 

PDP-11 Paper Tape Software Programmin g Handbook** 

(DEC-11-XPTSA-B-D) -- 

PDP-11 Processor Handbook * 

PDP-11 Peripherals Handbook * 

The following manual provides an introduction to the use of RT-11 by 
presenting a simple demonstration of basic operating procedures: 

RT-11 System Generation Manual * (DEC-ll-ORGMA-A-D) 

These manuals describe the capabilities of the optional high-level 
language components: y 


BASIC/RT-11 Language Reference Manual ** (DEC-ll-LBACA-D-D) 
PDP-11 FORTRAN Language Reference Manual ** (DEC-11-LFLRA-B-D) 
RT-ll/ RSTS/E FORTRAN IV User's Guide ** (DEC-ll-LRRUA-A-D) 


Summaries of the features provided by each language appear 
manual in Appendixes F and G respectively. 


in this 


Two PDP-11 system manuals are 
convert programs between DOS, 


helpful when using FILEX (Appendix J) to 
RSTS, and RT-11 formats: 


PDP-11 Resource Sharing Time-Sharing System User's Guide** 

(DEC-11-ORSUA-D-D) --- 

DOS/BATCH Handbook ** (DEC-ll-ODBHA-A-D) 


Users of display hardware may wish to refer 
hardware manual: 


to the appropriate 


GT40/42 User's Guide *** (39H150) 

GT44 User's Guide *** (39H250) 

VT11 Graphic Display Processor Manual *** (79H650) 

DECscope User's Manual *** (EK-VT50-OP) 

The experienced programmer will want to read the following manual: 

RT-11 Software Support Manual * (DEC-ll-ORPGA-B-D) 


*Included in the RT-11 Software Kit 

b u ordered from tne DIGITAL Software Distribution Center 

***May be ordered from DIGITAL Communication Services 
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Preface 


Consult the following for a list of all manuals available in the RT 11 
software documentation set: 

RT-11 Documentation Directory* (DEC-11-0RDDA-A-D) 


Documentation Conventions 

Conventions used throughout this manual include the following: 

1. Actual computer output is used in examples wherever possible. 
When necessary, computer output is underlined o 
differentiate from user responses. 


2 . 


A line feed (character or key) is represented in the text as 
<LF>; a carriage return (character or key) is represented as 
<CR>. Unless otherwise indicated, all commands and command 
strings are terminated by a carriage return. 


3. Terminal, console terminal, and teleprinter are general terms 
used throughout all RT-11 documentation to represent any 
terminal device, including DECwriters, displays, and 
Teletypes****. RP02 is a generic term used to represent botn 
the RP11C/RP02 and RPl1E/RPR02 disks. 

4. Several characters in system commands are produced b Y jYPing 
a combination of keys concurrently; for example, the CTRL 
key is held down while typing an 0 to produce a command which 
causes suppression of teleprinter output. Key combinations 
such as this are documented as CTRL 0, CTRL C, SHIFT N, and 
so forth. 


^Included in the RT-11 Software Kit 

★★★★Teletype is a registered trademark of the Teletype Corporation. 
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CHAPTER 1 
RT-11 OVERVIEW 


RT-11 is a single-user programming and operating system designed for 
the PDP-11 series of computers. This system permits the use of a wide 
range of peripherals and up to 28K of either solid state or core 
memory (hereafter referred to as memory). 

RT-11 provides two operating environments: Single-Job operation, and 
a powerful Foreground/Background (F/B) capability(1). 

Single-Job operation allows only one program to reside in memory at 
any time; execution of the program continues until either it is 
completed or it is physically interrupted by the user at the 
console. 

In a Foreground/Background environment, two independent programs may 
reside in memory. The foreground program is given priority and 
executes until it relinquishes control to the background program; the 
background program is allowed to execute until control is again 
required by the foreground program, and so on. This sharing of system 
resources greatly increases the efficiency of processor usage. 

To handle both operating environments, RT-11 offers two completely 
compatible and versatile monitors (Single-job and F/B); either monitor 
provides complete user control of the system from the console terminal 
keyboard. Monitor commands which allow the user to direct single-job, 
foreground, and background operations are described in Chapter 2. 

In addition to the monitor facilities, RT-11 offers a full complement 
of system programs; these allow program development using high level 
languages such as FORTRAN IV and BASIC or assembly language (MACRO or 
EXPAND/ASEMBL). System programs are summarized in Section 1.2 and are 
discussed in detail in individual chapters and appendixes of this 
manual. 


(1) The uses and advantages of each environment are outlined later in 
this chapter. 
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1•1 PROGRAM DEVELOPMENT 

Computer systems such as RT-11 are often used extensively for program 
development. The programmer makes use of the programming "tools” 
available on his system to develop programs which will perform 
functions specific to his needs. The number and type of "tools" 
available on any given system depend on a good many factors—the size 
of the system, its application and its cost, to name a few. Most 
DIGITAL systems, however, provide several basic program development 
aids: these generally include an editor, assembler, linker, debugger, 
and often a librarian; a high level language (such as FORTRAN IV or 
BASIC) is also usually available. 

An editor is used to create and modify textual material. Text may be 
the lines of code which make up a source program written in some 
programming language, or it may be data; text may be reports, or 
memos, or in fact may consist of any subject matter the user wishes. 
In this respect using an editor is analogous to using a 
typewriter—the user sits at a keyboard and types text. But the 
advantages of an editor far exceed those of a typewriter because once 
text has been created, it can be modified, relocated, replaced, 
merged, or deleted—all by means of simple editing commands. When the 
user is satisfied with his text, he can save it on a storage device 
where it is available for later reference. 

If the editor is used for the purpose of writing a source program, 
development does not stop with the creation of this program. Since 
the computer cannot understand any language but machine language 
(which is a set of binary command codes), an intermediary program is 
necessary which will convert source code into the instructions the 
computer can execute. This is the function of an assembler. 

The assembler accepts alphanumeric representations of PDP-11 coding 
instructions (i.e., mnemonics), interprets the code, and produces as 
output the appropriate object code. The user can direct the assembler 
to generate a listing of both the source code and binary output, as 
well as more specific listings which are helpful during the program 
debugging process. In addition, the assembler is capable of detecting 
certain common coding errors and of issuing appropriate warnings. 

The output produced by the assembler is called object output because 
it is composed of object (or binary) code. On PDP-11 systems, the 
object output is called a module and contains the user's source 
program in the binary language which is acceptable to a PDP-11 
computer. 

Source programs may be complete and functional by themselves; 
however, some programs are written in such a way that they must be 
used in conjunction with other programs (or modules) in order to form 
a complete and logical flow of instructions. For this reason the 
object code produced by the assembler must be relocatable—that is, 
assignment of memory locations must be deferred until the code is 
combined with all other necessary object modules. It is the purpose 
of linker to perform this relocation. 

The linker combines and relocates separately assembled object 
programs. The output produced by the linker consists of a load 
module, which is the final linked program ready for execution. The 
user can, at his option, request a load map which displays all 
addresses assigned by the linker. 
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Very rarely is a program created which does not contain at least one 
unintentional error, either in the logic of the program or in ITs 

editina hf«° rS may bS dlscovered b Y the programmer while he is 
ecJiting his program, or the assembler may find errors during the 
assembly proTOss and inform the programmer by means of error codes, 
he linker may also catch certain errors and issue appropriate 
messages. Often, however, it is not until execution that P th e P user 

f^ rS is nob working properly. Programming errors may 

be extremely difficult to find, and for this reason a debugging tool 
is usually available to aid the programmer in determining the cause of 


A debugging program allows the user to interactively control the 
execution of his program. With it, he can examine the contents of 
individual locations, search for specific bit patterns, set designated 
stopping points during execution, change the contents of locations, 
continue execution, and test the results, all without the need of 
re-editing and re-assembling. 

When programs are successfully written and executed, they may be 

? 0t K Gr Pr°9 ramme fs. Often routines which are common to many 
programs (such as I/O routines) or sections of code which are used 
over again, are more useful if they are placed in a library 
where they can be retrieved by any interested user. A librarian 

service allowing creation of a library file. Once 
created, the library can be expanded, updated, or listed. 

High level languages simplify the programmer's work by providing an 
alternate means of writing a source program other than assembly 
language mnemonics. Generally, high level languages are easy to 

Sin H ® f? Itlinand m *y cause the computer to perform many machine 
language instructions. The user does not need to know about the 
mechanics of the computer to use a high level language. In addition, 
^ h ;hl J?.level languages (like BASIC) offer a special immediate mode 
which allows the user to solve equations and formulas as though he 
were using a calculator. Assembling and linking are done 

rathpr^h 31 ^ • SO ^£ at the user can concentrate on solving the problem 
rather than using the system. 

These are a few of the programming tools offered by most computer 

avai? 3 hif» +• m-, next section summarizes specific programming aids 

available to the user of RT-11. ^ 


1.2 SYSTEM SOFTWARE COMPONENTS 

The following is a brief summary of the RT-11 system programs: 


1 . 


2 . 


The Text Editor (EDIT, described in Chapter 3) is used to 
create or modify source files for use as input to language 
processing programs such as the assembler or FORTRAN. EDIT 
contains powerful text manipulation commands for quick and 
easy editing of a text file. EDIT also allows use of a VT11 
display processor (such as the GT44), if one is part of the 
hardware configuration (see Section 1.3). 

The MACRO Assembler (Chapter 5) brings the capabilities of 
t0 RT ~} 1 system with 12K (or more) memory. 

arS lns truetions in a source or command language 
which are equivalent to a specified sequence of machine 
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instructions or commands.) The assembler accepts source files 
written in the MACRO language and generates a relocatable 
object module to be processed by the Linker before fading 
and execution. Cross reference listings of assembled 
programs may be produced using CREF in conjunction with the 
MACRO Assembler. 

EXPAND (Chapter 10) is used in an 8K F/B job area or 8K 
systems (or in larger systems with programs of great size) to 
expand macros in an assembly language program into macro-free 
source code, thus allowing the program to be assembled in 8K 
using ASEMBL. 

ASEMBL (Chapter 11) is an assembler designed for use in an 8K 
RT-11 system, an 8K F/B job area, or larger systems where 
symbol table space is a factor. ASEMBL is a subset of 
MACRO-11 with more limited features. (CREF is not available 
under ASEMBL.) 


5. 


6 . 


7. 


8 . 


The Linker (LINK, described in Chapter 6) fixes (i.e., makes 
absolute) the values of relocatable symbols and converts the 
relocatable object modules of compiled or assembled programs 
and subroutines into a load module which can be loaded and 
executed by RT-11. LINK can automatically search library 
files for specified modules and entry points; it can produce 
a load map (which lists the assigned absolute addresses) and 
can provide automatic overlay capabilities to very large 
programs. The Linker can also produce files suitable for 
running in the foreground. 


The Librarian (LIBR, see Chapter 7) allows the user to create 
and maintain his own library of functions and routines. 
These routines are stored on a random access device as 
library files 9 where they can be referenced by the Linker. 


The Peripheral Interchange Program (PIP, see chapter 4) is 
the RT-11 file maintenance and utility program. It is used 
to transfer files between all devices which are part of the 
RT-11 system, to rename or delete files, and to obtain 
directory listings. 

SRCCOM (Source Compare, described in Appendix K) allows the 
user to perform a character-by-character comparison of two or 
more text files. Differences can be listed in an output file 
or directly on the line printer or terminal, thus providing a 
fast method of determining, for example, if all edits to a 
file have been correctly made. 


9. 


FILEX (Appendix J) allows file transfers to occur between 
DECtapes used under the DECsystem-10 or PDP-11 RSTS system, 
and DECtape and disk used under the DOS/BATCH system, and any 
RT-11 device. 


10. The PATCH utility program (Appendix L) is used to make minor 
modifications to memory image files (output files produced by 
the Linker); it is used on files which do or do not have 
overlays. PATCHO (Appendix M) is used to make minor 
modifications to files in object format (output files 
produced by the FORTRAN compiler and the Librarian, or MACRO 
and ASEMBL assemblers). 
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11. ODT (On-line Debugging Technique, described in Chapter 8) 
aids in debugging assembled and linked object programs, it 
can print the contents of specified locations, execute all or 
part of the object program, single step through the object 
program, and search the object program for bit patterns. 

12. DUMP (Appendix I) is used to print for examination all or any 
part of a file in octal words, octal bytes, ASCII and/or 
RAD50 characters (see Chapter 5). 


13 ' allows 12 * 1S a com P le te job control language that 
allows RT-11 to operate unattended. The BATCH stream may be 

° f f'i 1 monitor commands or system-independent 
ATCH jobs (jobs that will run on any DIGITAL system 

RamrH rt i ng the BAT £ H standard; currently RT-11 and RSX-11D). 
BATCH streams can be executed under the Single-Job Monitor 
or in the background under the F/B Monitor. 

The RT-11 FORTRAN System Subroutine Library (SYSLIB, Appendix 
0) is a collection of FORTRAN callable routines that make the 
programmed requests and various utility functions availabll 
to the FORTRAN programmer. SYSLIB also provides a complete 

RT-li g FORTRAN latl ° n paCkage and tw °- w °rd integer package for 

an f F0RT ? AN I Y are , two high level languages available under 
RT-ll. Summaries of their language features and commands are provided 
in Appendixes F and G of this manual* 


14. 


1*3 SYSTEM HARDWARE COMPONENTS 


The minimum RT 11 system (that is, one that does not use the F/B 
capability) requires a PDP-11 series computer with at least 8K of 
memory,. a random-access device, and a console terminal. The F/B 
capability requires at least 16K of memory and a line frequency clock. 
For specific hardware/software interdependent requirements, refer to 
the RT-11 System Release Notes. 


supported by RT-11 are listed in Table 1-1. The third 

• fh 1S c ° lumn 1 ^? ts devices for which support is initially provided 
in the system as distributed; these devices can be used with no 

The lf o Catl0n (t ° 61 ^ her the monitor tables or the handlers) necessary. 

*° eS t fourth coiunm are supported after simple 

modifications to the monitor tables or handlers. The system 

hoi t to 1 m^ 1 °th SeCtl °^-^ th Y RT - 1:1 - System Generation Manual describes 
£hL£ k these modification?: Tne tifth column lists devices for 

c£r?entiv SUP the t ' • bu Y. which raay be interfaced by the user. 

th e <3; !' Sk 1S the ° nly device in this category, and 

Support Manual interface are provided in the RT-11_ Software 


Consult the RT-11 System Generation Manual for 
be made to existing system devices (for example, 
of a terminal). 


modifications that may 
varying the baud rate 
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Table 1-1 

RT-11 Hardware Components 


Category 

Controller 

System-Installed 
Devices 

Devices Re¬ 
quiring System 
Modification 

User-Installed 

Devices 

DISK 





DECpack 

RKll 

RK05 



Cartridge 





Fixed-head 

RF11 

RS11 




RC11 



RS64 


RH11 

RJS03 

RJS04 


Removable 

RPll 

RP02 

RP03 


Pack 





Diskette 

RXll 

RX01 

RX01 (second 





controller) 


DECTAPE 

TC11 

TU56 



MAGTAPE 

TM11/TMA11 

TU10,TS03 




KH11 

TJU16 



CASSETTE 

TA11 

TU60 



HIGH-SPEED 

PC11 

PC11 (both) 



PAPER TAPE 

PR11 

PR11 (reader only) 



READER/PUNCH 





LINE PRINTER 

LS11 

LS11, LA180 




LV11 

LV11 (printer only) 




LPll 

all LPll controlled 





printers 



CARD READER 

CR11 


CR11 



CM11 


CM11 


TERMINAL 

DL11 

LT33, LT35 





LA30P, LA36, 

LA30S 




VT50, VT52, 





VT05 



DISPLAY 

VT11 

VR14-L,VR17-L 



PROCESSOR 





CLOCK 


KW11-L 




January 1976 


1-6 



























RT-±± Overview 


RT-il o pera te s in environments ranging from 8K to 28K words of memory. 
Reconfiguration for different memory sizes is unnecessary—the same 
system device operates on any PDP-11 processor with 8K to 28K of 
memory and makes use of all memory available. 


1.4 USING THE RT-11 SYSTEM 

As mentioned earlier in the chapter, the RT-11 system offers two 
complete operating environments. Each is controlled by a single user 
from the console terminal keyboard by means of an appropriate 
monitor—Single-Job or Foreground/Background. Both monitors are 
completely compatible and allow full user interaction with all 
features which are a part of the operating environment in use. 

The choice of which environment to use, and, consequently, which 
monitor to run, depends upon the needs of the user. The next two 
sections provide information useful in determining which monitor is 
more suitable for certain applications. 


1.4.1 RT-11 Single-Job Monitor 

The RT—11 Single—Job Monitor provides a single-user, single—program 
system which can operate in as little as 8K of memory. Since the 
Single-Job Monitor itself requires approximately one-half the memory 
space needed by the Foreground/Background Monitor, this system is 
ideal for extensive program development work; a much larger area of 
memory is available for the user program and its buffers and tables. 
Programs requiring extremely high data rates are best run in the 
Single-Job environment, since interrupts can be serviced at a much 
higher rate. 


All system programs (listed in Section 1.2) can be used under the 
Single-Job Monitor, and many of the features of the 
Foreground/Background Monitor (i.e., KMON commands and programmed 
requests not used to control foreground jobs) are supported. 

In effect, the Single-Job Monitor is much smaller and slightly faster 
than the Foreground/Background Monitor; it can best be used when 
program size is the important factor. 


1.4.2 RT-11 Foreground/Background Monitor 

Quite often the central processor of a computer system may spend a 
large percentage of time waiting for some external event to occur, the 
most common event being the completion of an I/O transfer (this is 
particularly true of real time jobs). Many users would like to take 
advantage of this unused capacity to accomplish other lower—priority 
tasks such as further program development or complex data analysis. 
The Foreground/Background system provides this capability. 

In a Foreground/Background system the foreground job is the 
time—critical, on-line job, and is given top priority; whenever 
possible the processor runs the foreground job. However, when the 
^ 0] - e U^o uri d job reaches a state in which no more processing can be done 
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until some external event occurs, the monitor will try to run the 
lower priority background job. The background job then runs until the 
foreground job is again in a runnable state, at which point the 
processor will interrupt the background job and resume the foreground 
job. 

In general, the RT-11 Foreground/Background System is designed to 
allow a time-critical job to run in the foreground, while the 
background does non-time-critical jobs, such as program development. 
(All RT-11 system programs run as the background job in a F/B system.) 
Thus, the user can run FORTRAN, BASIC, MACRO, etc. in the background 
while the foreground may be collecting data and storing and/or 
analyzing it. 

Most user programs written for an RT-11 System can be linked (using 
the Linker described in Chapter 6) to run as the foreground 30 b. 
There are a few coding restrictions, and these are explained in 
Appendix H, F/B Programming and Device Handlers. A foreground program 
has access to all of the features available to the background 30 b 
(opening and closing files, reading and writing data, etc.). In 
addition, the F/B System gives the user the ability to set timer 
routines, suspend and resume F/B jobs, and send data and messages 
between the two jobs. 


1.4.3 Facilities Available Only in RT-11 F/B 

As mentioned previously, RT-11 F/B allows the user to write and 
execute two independent programs. Some features which are available 
only to the F/B user include: 

1. Mark Time—This facility allows user programs to set clock 
timers to run for specified amounts of time. When the timer 
runs out, a routine specified by the user is entered. There 
may be as many mark time requests as desired, providing 
system queue space is reserved (see .QSET, Chapter 9). 

2. Timed Wait—This feature allows the user program to "sleep" 
until the specified time increment elapses. Typically, a 
program may need to sample data every few seconds or even 
minutes. While the program is idle, the other job can run. 
The timed wait accomplishes this; when the time has elapsed, 
the issuing job is again runnable (see .TWAIT, Chapter 9). 

3. Send Data/Receive Data—It is possible, under RT-11 F/B, to 
have the foreground and background programs communicate with 
one another. This is accomplished with the send/receive data 
functions. Using this facility, one program sends messages 
(or data) in variable size blocks to the other job. This can 
be used, for example, to pass data from a foreground 
collection program directly to a background analysis program 
(see .SDAT/.RCVD, Chapter 9). 
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CHAPTER 2 

SYSTEM COMMUNICATION 


The monitor is the hub of RT-11 system communications; it provides 
access to system and user programs, performs input and output 
functions, and enables control of background and foreground jobs. 

The user communicates with the monitor through programmed requests and 
keyboard commands. The keyboard commands (described in Section 2,7) 
are used to load and run programs, start or restart programs at 
specific addresses, modify the contents of memory, and assign and 
deassign alternate device names. 

Programmed requests (described in detail in Chapter 9) are source 
program instructions which pass arguments to the monitor and request 
monitor services. These instructions allow user assembly language 
programs to utilize the available monitor features. 


2,1 START PROCEDURE 

After the system has been built (see the RT-11 System Generation 
Manual ), the monitor can be loaded into memory from disk or DECtape as 
follows: 


1. Press HALT. 

2. Mount the system device on unit 0 (or the appropriate unit if 
a unit other than 0 is to be used). 

3. WRITE PROTECT the system unit. 

If the hardware configuration includes a hardware bootstrap capable of 
booting the system device, 

1. Set the switch register to the appropriate address and press 
LOAD ADRS. 

2. If a second address is required, set the switch register to 
that address. 

3. Press START. 
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If a hardware bootstrap is not available, or if an RK disk unit 

other than 0 is to be used as the system device, one of the following 
bootstraps must be entered manually using the Switch Register. First 
set the Switch Register to 1000 and press the LOAD ADRS switch. Then 
set the Switch Register to the first value shown for the appropriate 
bootstrap and raise the DEPosit switch. Continue depositing the 
values shown. 


105710 

100376 

5007 


* xxxxxx = 20000 

for 

unit 

1 

40000 

for 

unit 

2 

60000 

for 

unit 

3 

100000 

for 

unit 

4 

120000 

for 

unit 

5 

140000 

for 

unit 

6 

160000 

for 

unit 

7 


DECtape 

(RK Disk other 
(RKll,RK05) than Unit 0) 

Disk 

(RF11) 

(RJS03/4) 

(RP11/R 

12700 

12700 

12700 

12700 

12705 

12705 

177344 

177406 

177406 

177466 

172044 

176716 

12710 

12710 

12760 

5010 

12745 

12715 

177400 

177400 

xxxxxx * 

5040 

177400 

177400 

12740 

12740 

4 

12740 

12745 

12745 

4002 

5 

12700 

177400 

71 

5 

5710 

105710 

177406 

12740 

32715 

105715 

100376 

100376 

12710 

5 

100200 

100376 

12710 

5007 

177400 

105710 

1775 

5007 

3 


12740 

100376 

100762 


105710 


5 

5007 

5007 


100376 


105710 




12710 


100376 




5 


5007 





** n = 4 for unit 0 
6 for unit 1 


12702 

1002n7** 

12701 

177170 

130211 

1776 

112703 . 

7 

10100 

10220 

402 

12710 

1 

6203 

103402 

112711 

111023 

30211 

1776 

100756 

103766 

105711 

100771 

5000 

22710 

240 

1347 

122702 

247 

5500 

5007 




When all the values have been entered, set the switches to 1000 and 
press the LOAD ADRS and START switches. 

The monitor loads into memory and prints one of the following 
identification messages followed by a dot (.) on the terminal: 

RT-11SJ V02C-XX 
RT-llFB V02C-XX 

The message printed indicates which monitor (Single-Job or F/B) has 
been loaded; the user may determine which is to be loaded during the 

system build operation. 

After the message has printed , the system device should be WRITE 
ENABLED. The monitor is ready to accept keyboard commands. 
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To bring up an alternate monitor whil.e under control of the one 
currently running (in this case, F/B), run PIP to perform the following 
operations: 

1. Preserve the running monitor by renaming it to yyyyyy.SYS 
(the actual name yyyyyy is not significant, although it is 
suggested that yyMNSJ for Single-Job and yyMNFB for Fore¬ 
ground/Background be used to be consistent with system con¬ 
ventions; yy in this case represents the disk type): 

,R PIP 

*RK8 ;RKMNFB.SVS-RK0:MON ITR. SVS/R/Y 
7REB00T? 


2. Rename the desired monitor to MONITR.SYS: 


*RK0:MONITR.SVS-RK0:RKMNSJ. SVS/RVV 
7REBOOT? 


3. Write the new bootstrap from the new MONITR.SYS file 
(using the PIP /U option; A is a dummy filename, which 
must be present in the command line): 

lRK0:fl = RK0 rMONITR.SVS/U 


4 



Reboot the system. 
±RKQ :/0 

RT-iiSJ V02C-82 


Refer to the RT-11 System Generation Manual for an example of switching 
monitors. 
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2.2 SYSTEM CONVENTIONS 


Special character commands, file naming procedures 
conventions that are standard for the RT-11 system are 
this section. The user should be familiar with these 
before running the system. 


and other 
described in 
conventions 


2.2.1 Data Formats 

The RT-11 system makes use of five types of data formats: 
object, memory image, relocatable image, and load image. 


ASCII, 


Files in ASCII format conform to the American National Standard Code 
f°£ x ?£ ormatlon Interchange, in which each character is represented by 
3 K° d fu F £f es in ASCXI format include program source files 

created by the Editor, listing and map files created by various system 
programs, and data files consisting of alphanumeric characters. A 
chart containing ASCII character codes appears in Appendix C. 

Hil 3 in ° bje f t £??“ at consist of data and PDP-11 machine language 
• Object files are those output by the assembler or FORTRAN 
compiler and are used as input to the Linker. 


The Linker can output files in memory image format (.SAV), 
image format (.REL), or load image format (.LDA). 


relocatable 


A memory image file (.SAV) is a 'picture' of what 
like when a program is loaded. The file itself 
number of disk blocks as the corresponding number of 
blocks. 


memory will look 
requires the same 
256-word memory 


A relocatable image file (.REL) is one which can be run in the 
foreground. it differs from a memory image file in that the file is 
though * ts bottom address were 0. When the program is called 
£ h ® monitor FRUN command) , the file is relocated as it is 
loaded into memory. (A memory image file requires no such 
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a load imaae (or .LDA) file may be produced for compatibility with the 
PDP°n 1 Paper Tape System and is loaded by the absolute binary loader. 
lda files can be loaded and executed in stand-alone environments 
without relocation. 


2.2.2 Prompting Characters 

The following table summarizes the characters typed by RT-11 to 

indicate to 9 the user either that the system is awaiting ?® er 

or to specify which job (foreground or background) is producing 


output: 

Table 2-1 

Prompting Characters 

Character 

Meaning 

• 

The Keyboard Monitor is waiting for a command (see 
Section 2.3.2). 

* 

The Command String Interpreter is waiting for a 
command string specification as explained in 
Sections 2.3.3 and 2.5. 

t 

When the console terminal is being used as an 
input file, the uparrow prompts the user to enter 
information from the keyboard. If the input is 
entered under EDIT or BASIC (or any program that 
accepts input in special terminal mode as 
described in Chapter 9), the characters entered 
are not echoed. Typing a CTRL Z marks the 
end-of-file. 

> 

The > character is used (under the F/B Monitor and 
only if a foreground job is active) to identify 
which job, foreground or background, is producing 
the output currently appearing on the console 
terminal. Each time output from the background 
job is to appear, B> is printed first, followed by 
the output. If the foreground job is to print 
output, F> is typed first. B> and F> are also 
printed as a result of the CTRL B and CTRL F 
commands described in Table 2—4. 


2.2.3 Physical Device Names 

Devices are referenced by means of a standard two-character device 
name. Table 2-2 lists each name and its related device. If no unit 
number is specified for devices which have more than one unit, unit 0 
is assumed. 
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Table 2-2 



Permanent Device Names 

Permanent Name 

I/O Device 

CRs 

Card Reader (CR11/CM11). 

CTn: 

TA11 cassette (n is the unit number, 0 or 1). 

DKs 

The default logical storage device for all files. 

DK is initially the same as SY: (see below), but the 
assignment (as a logical device name) can be changed 
with the ASSIGN Command (Section 2.7.2.4). 

DKn: 

The specified unit of the same device type as DK. 

DPn: 

RP02 disk (n is an integer in the range 0-7). 

DSn: 

RJS03/4 fixed-head disks (n is in the range 0-7). 

DTns 

DECtape n, where n is a unit number (an integer in 
the range 0 to 7, inclusive). 

DXn 2 

RX01 Floppy disk (n is 0 or 1). 

LP: 

Line printer. 

MMn: 

TJU16 magtape (n is in the range 0-7). 

MTn: 

TM11 (industry compatible) magtape (n is an integer 

between 0 and 7, inclusive). 

PPs 

High-speed paper tape punch. 

PR: 

High-speed paper tape reader. 

RF: 

RF11 fixed-head disk drive. 

RKn: 

RK disk cartridge drive n (n is in the range 0 to 

7 inclusive). 

SY: 

System device; the device and unit from which the 
system is bootstrapped. (RT-11 allows 

bootstrapping from any kk unit; refer to Section 
2.1.) The assignment as a logical device name can 
be changed with the ASSIGN command (Section 2.7.2.4). 

SYn: 

The specified unit of the same device type as that 
from which the system was bootstrapped. 

TT: 

Terminal keyboard and printer. 


In addition to the fixed names shown in Table 2-2, devices can be 
assigned logical names. A logical name takes precedence over a 
physical name and thus provides device independence. With this 
feature a program that is coded to use a specific device does not need 
to be rewritten if the device is unavailable. Refer to Section 

2.7.2.4 for instructions on assigning logical names to devices. 

2.2.4 File Names and Extensions 

Files are referenced symbolically by a name of one to six alphanumeric 
characters followed, optionally, by a period and an extension of up to 
three alphanumeric characters. (Excess characters in a filename may 
cause an error message.) The extension to a filename generally 
indicates the format of a file. It is a good practice to conform to 
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the standard filename extensions for RT-11. If an extension is not 
specified for an input or output file, most system programs assign 
appropriate default extensions. Table 2-3 lists the standard 
extensions used in RT-11. 

Table 2-3 



File Name Extensions 

Extension 

Meaning 

.BAD 

Files with bad (unreadable) blocks; this 
extension can be assigned by the user 
whenever bad areas occur on a device. The 
.BAD extension makes the file permanent in 
that area, preventing other files from using 
it and consequently becoming unreadable. 

.BAK 

Editor backup file. 

.BAS 

BASIC source file (BASIC input). 

.BAT 

BATCH command file. 

.CTL 

BATCH control file generated by the 

BATCH compiler. 

• CTT 

BATCH internal temporary file. 

.DAT 

BASIC or FORTRAN data file. 

.DIR 

Directory listing file 

.DMP 

DUMP output file. 

.FOR 

FORTRAN IV source file (FORTRAN input). 

• LDA 

Absolute binary file (optional Linker 

output). 

• LLD 

Library listing file. 

.LOG 

BATCH log file. 

• LST 

Listing file (MACRO or FORTRAN output). 

.mac 

MACRO or EXPAND source file (MACRO, EXPAND, 
SRCCOM input). 

.MAP 

Map file (Linker output). 

.OBJ 

Relocatable binary file (MACRO, ASEMBL, 
FORTRAN IV output. Linker input, LIBR input 
and output). 

.PAL 

Output file of EXPAND (the MACRO expander 
program), input file of ASEMBL. 

.REL 

Foreground job relocatable image (Linker 

output, default for monitor FRUN command). 

.SAV 

Memory image or SAVE file; default for R, 
RUN, SAVE and GET Keyboard Monitor commands; 
also default for output of Linker. 

.SOU 

Temporary source file generated by BATCH. 

.SYS 

System files and handlers. 
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If a filename with a blank extension is to be used in a command line 
in which a default extension is assumed (by either the monitor or a 
system program), the user must insert a period after the filename to 
indicate that there is no extension. For example, to run the file 
TEST, type: 

.RUN TEST. 

If the period after the filename is not given, the monitor assumes the 
•SAV extension and attempts to run a file named TEST.SAV. 


2.2.5 Device Structures 

RT-11 devices are categorized by the physical structure of the device 
and the way in which the device allows information to be processed. 

All RT-11 devices are either random-access or sequential-access devices. 
Random-access devices allow blocks of data to be processed in a random 
order — that is, independent of the data's physical location on the 
device or its location relative to any other information. All disks 
and DECtape fall into this category. Random-access devices are some¬ 
times also called block-replaceable devices, because individual data 
blocks can be manipulated (rewritten) without affecting other data 
blocks on the device. Sequential-access devices require that data be 
processed sequentially; the order of processing data must be the same 
as the physical order of the data. RT-11 devices that are considered 
sequential devices are magtape, cassette, paper tape, card reader, 
line printer, and terminal. 

File-structured devices are those devices that allow the storage of 
data under assigned filenames. RT-11 devices that are file-structured 
include all disks, DECtape, magtape, and cassette. Nonfile-structured 
devices, on the other hand, are those used to contain a single logical 
collection of data. These devices are used generally for reading and 
listing information, and include line printer, card reader, terminal, 
and paper tape devices. 

Finally, file-structured devices are classified further as RT-11 direc ¬ 
tory-structured devices if they provide a standard RT-11 directory at 
the. beginning of the device (the standard RT-11 directory is defined 
in the RT-11 Software Support Manual ). The directory contains informa¬ 
tion about all files stored on the device and is updated each time a 
file is moved, added, or deleted from the device. RT-11 directory- 
structured devices include all disks and DECtapes. NonRT-11 directory- 
structured devices are file-structured devices that do not have the 
standard RT-11 directory structure at their beginning. For example, 
some devices, such as magtape and cassette, have directory-type infor¬ 
mation stored at the beginning of each file; the device must be read 
sequentially to obtain all information about all files. 

It is possible to interface a device to the RT-11 system with a user- 
defined directory structure; procedures are explained in the RT-11 
Software Support Manual . 
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2.3 MONITOR SOFTWARE COMPONENTS 

The main RT-11 monitor software components are: 

Resident Monitor (RMON) 

Keyboard Monitor (KMON) 

User Service Routine (USR) and Command String Interpreter (CSI) 
Device Handlers 

The reader may find Figure 2-1 helpful while reading the following 
descriptions. 


2.3.1 Resident Monitor (RMON) 

The Resident Monitor is the only permanently memory-resident part of 
RT-11. The programmed requests for all services of RT-11 are handled 
by RMON. RMON also contains the console terminal service, error 
processor, system device handler , EMT processor , and system tables. 


2.3.2 Keyboard Monitor (KMON) 

The Keyboard Monitor provides communication between the user at the 
console and the RT-11 system. Monitor commands allow the user to 
assign logical names to devices, run programs, load device handlers , 
and control F/B operations. A dot at the left margin of the console 
terminal page indicates that the Keyboard Monitor is in memory and is 
waiting for a user command. 


2.3.3 User Service Routine (USR) 

The User Service Routine provides support for the RT-11 file 
structure. It loads device handlers, opens files for read or write 
operations , deletes and renames files, and creates new files. The 
Command String Interpreter (the use of which is described in Section 
2.5) is part of the USR and can be accessed by any program to 
interpret device and file I/O information. 
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2,3.4 Device Handlers 

Device handlers for the RT-11 system perform the actual transfer of 
data to and from peripheral devices. New handlers can be added to the 
system as files on the system device and can be interfaced to the 
system by modifying a few monitor tables (see the RT-11 Software 
Support Manual/ DEC-11-ORPGA-B-D for instructions on how to interface 
a new handler to the RT-11 monitor). 


2.4 GENERAL MEMORY LAYOUT 

When the RT-11 System is first bootstrapped from the system device, 
memory is arranged as shown in the left diagram of Figure 2-1 (this is 
the case for either the Single-Job or Foreground/Background Monitor/ 
since no foreground job exists yet). The background job is the RT-11 
module KMON. 

When an RT-11 foreground job is initiated (via the monitor FRUN 
command/ Section 2.7.5.1), room is created for the foreground job to 
be loaded by decreasing the amount of space available to the 
background job. The memory maps in Figure 2-1 illustrate the system 
layout before and after a foreground job is loaded. (Refer also to 
Chapter 6/ Section 6.5.) 


BEFORE 

LOADING 

THE 

FOREGROUM) 

JOB 


RMON 



RMON 

USR 



HANDLERS 

KMON 



FJOB 




USR 


HIGH 

ADDRESSES 

KMON 

i 

1 




AFTER 

LOADING 

THE 

FOREGROUND 

JOB 


Figure 2-1 

RT-11 System Memory Maps 

As shown in the figures/ the process of loading a foreground job 
requires that the USR and KMON be physically moved. Once a foreground 
job is running, it is possible to communicate with either the 
background or foreground job via special commands (described in 
Section 2.7). All of the terminal support functions described in 
Section 2.6 are available under both the Single-job and F/B Monitors. 

In addition to FRUN/ other monitor commands can alter the memory map; 
these are LOAD/ UNLOAD/ GT ON/ and GT OFF. LOAD causes device 
handlers to be made resident until an UNLOAD command is performed. 
UNLOAD deletes handlers which have been loaded. GT ON and GT OFF 
cause terminal service to utilize the VT-11 display hardware. Figure 
2-2 illustrates the placement of display modules and device handlers 
in memory following the GT 0N # LOAD/ and FRUN commands: 
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Figure 2-2 

RT-11 Memory Map (GT40) 


RT-11 maintains a free memory list to manage memory. Thus, when 
handler is unloaded, the space the handler occupied is returned to 
memory list and is reclaimed by the background. 


a 

the 


2.4.1 Component Sizes 


Following are the approximate sizes (in words) of the 
RT-11, Version 2C (sizes reflect RK). 


components for 


RMON 

USR 

KMON 


F/B 

3575(10) 

2050(10) 

1800(10) 


Single-job 

1703(10) 

2050(10) 

1540(10) 


In the F/B system, the background area must always be large enough to 
hold KMON and USR (3.9K words). The following liJt indicates Setota? 
space avallab le for the loaded device handlers, the foreground job, 
and the display handler. Note that the low memory area from 0-477 is 
the**. SERMON* 6XeCUtable programs * (These sizes also allow room for 


Machine size (words) 

16K 

24K 

28K 


Space available (words) 

8.5K 
16.5K 
20.5K 


With the Single-Job Monitor, RMON requires only 1.67K. The following 

list shows the amount of space available to users with the Single-Job 
Monitor: J 
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Machine size (words) Program space avail able (words) 


8 K 

16K 

24K 

28K 


6 K 

14K 

22K 

26K 


2 5 ENTERING COMMAND INFORMATION 

Once either monitor has been loaded and a system program started, the 
user must enter the appropriate command information before any opera- 
tion can be performed. 

In most cases, the Command String Interpreter immediately prints an 
asterisk at the left margin. The user must then type a command string 
in the general formats 

OUTPUT=INPUT/SWITCH 

(A few system programs — EDIT, PATCH, PATCHO — require that this com¬ 
mand information be entered in a slightly different format. Comple 
instructions are provided in the appropriate chapter.) 

In all cases, the format for OUTPUT is: 

devs filnam.ext[n],...dev:filnam.ext[n] 


INPUT is: 


dev:filnam.ext , ••.dev:filnam.ext 
| and SWITCH is: 

/s:oval or /sldval 


where: 

dev: 


filnara.ext 


I 


[n] 


/s:oval or 
/s!dval 


in each case is am optional two to three-character 
name from Table 2-2 whose usage conforms to the 
NOTE below. 

in each case is the name of a file (consisting of 
one to six alphanumeric characters followed 
optionally by a dot and a zero to three—character 
extension). As many as three output and six input 
files may be allowed. 

is an optional declaration of the number of blocks 
(n) desired for an output file, n is a decimal 
number (<65,535) enclosed in square brackets 
immediately following the output filnam.ext to 
which it applies. 

is one or more optional switches whose functions 
vary according to the program in use (refer to the 
switch option table in the appropriate chapter)• 
oval is either an octal number or one to three 
alphanumeric characters (the first of which must 
be alphabetic) which will be converted to radix-50 
(see Section 5.5.4 of the MACRO chapter), dval is 
a decimal value preceded by an exclamation point. 
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Throughout this manual, the /ssoval construction 
is used; however, the /sldval format is always 
valid. Generally, these switches and their 
associated values, if any, should follow the 
device and filename to which they apply. 

If the same switch is to be repeated several times 
with different values (e.g., /L:MEB/L:TTM/L:CND to 
MACRO) the line may be abbreviated as 
/L:MEB:TTM:CND; octal, RAD50, and decimal values 
may be mixed. 

if required, is a delimiter that separates the out¬ 
put and input fields. The < sign may be used in 
place of the = sign. The separator can be omitted 
entirely if there are no output files. 


NOTE 

As illustrated in the general format of 
a command line, the command line 
consists of an output list, a separator 

(= or <), and an input list. 
Omission of a device specification in 
either the input or output list is han¬ 
dled as follows: 


DKs is assumed if the first file in a 
list has no explicit device. DK (or the 
device associated with the first file) 
is default until another device is 
indicated; that device then becomes 
default until a new one is used, and so 
on. If the following command is 
entered, for example, to MACRO: 

* DTI : FIRST. OB J, LP : = TASK, i, RK1 : TftSK. 2 , TASK. 2 

it is interpreted as though all devices 
had been indicated as follows: 

+ DT1 FIRST. OBJ, LP : = DK : TftSK. 1, RK1 : TftSK. 2, RKi : TftSK. 2 


2.6 KEYBOARD COMMUNICATION (KMON) 

Special function keys and keyboard commands allow the user to 
communicate with the RT-11 monitor and allocate system 
resources, manipulate memory images, start programs, and use 
foreground/background services. 

The special functions of certain terminal keys used for communication 
with the Keyboard Monitor are explained in Table 2-4. Note that in the 
F/B system, the Keyboard Monitor always runs as a background job. 

CTRL commands are entered by holding the CTRL key down while typing 
the appropriate letter. 
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Table 2-4 

Special Function Keys 

Key 

Function 

CTRL A 

Valid when the monitor GT ON command has been typed and 
the display is in use. The command does not echo on 
the terminal. It is used after a CTRL S has been typed 
to effectively page output. Console output is 
permitted to resume until the screen is completely 
filled; text previously displayed is scrolled upward 
off the screen. CTRL A has no special meaning if GT ON 
is not in effect or if a SET TTY NOPAGE command has 
been given (see Section 2.7.2.8). 

CTRL B 

Under the F/B Monitor echoes B> on the terminal (unless 
output is already coming from the background job) and 
causes all keyboard input to be directed to the 
background job. At least one line of output will be 
taken from the background job (the foreground job has 
priority, and control will revert to it if it has 
output), All typed input will be directed to the 
background job until control is redirected to the 
foreground job (via CTRL F)• CTRL B has no special 
meaning when used under a Single-Job Monitor or when a 
SET TTY NOFB command has been issued (see Section 

2 .7.2.8). 

CTRL C 

CTRL C echoes as on the terminal and is used to 
interrupt program execution and return control to the 
keyboard monitor. If the program to be interrupted is 
waiting for terminal input, or is using the TT handler 
for input, typing one CTRL C is sufficient to interrupt 
execution? in all other cases, two CTRL Cs are neces¬ 
sary. Note that under the F/B Monitor, the job which is 
currently receiving input will be the job that is stopped 
(determined by whether a CTRL F or CTRL B was most re¬ 
cently typed). To ensure that the command is directed 
to the proper job, type CTRL B or CTRL F before typing 
CTRL C. 

CTRL E 

Valid when the monitor GT ON command has been typed and 
the display is in use. The command does not echo on 
the terminal, but causes all terminal output to appear 
on both the display screen and the console terminal 
simultaneously. A second CTRL E disables console 
terminal output. CTRL E has no special meaning if 

GT ON is not in effect. 

CTRL F 

Under the F/B Monitor echoes F> on the terminal and 
instructs that all keyboard input be directed to the 
foreground job and all output be taken from the 
foreground job. If no foreground job exists, F? is 
printed and control is directed to the background job. 
Otherwise, control remains with the foreground job 
until redirected to the background job (via CTRL B) or 
until the foreground job terminates. CTRL F has no 
special meaning when used under a Single-Job Monitor, 
or when a SET TTY NOFB command has been used (see 
Section 2.7.2.8), 
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Table 2-4 (Cont.) 
Special Function Keys 


Key 

Function 

CTRL 0 

Echoes to on the terminal and causes suppression of 

teleprinter output while continuing program execution. 
Teleprinter output is re-enabled when one of the 
following occurs: 


1• A second CTRL 0 is typed, 


2 • A return to the monitor occurs , or 


3. The running program issues a .RCTRLO 

directive (see Chapter 9). (RT-11 system 

programs reset CTRL 0 to the echoing state 
each time a new command string is entered.) 

CTRL Q 

Does not echo. Resumes printing characters on the 
terminal from the point at which printing was 
previously stopped (via CTRL S). CTRL Q has no special 
meaning if a SET TTY NOPAGE command has been used (see 
Section 2.7.2.8). 

CTRL S 

Does not echo. Temporarily suspends output to the 
terminal until a CTRL Q is typed. If GT ON is in 
effect, each subsequent CTRL A causes output to proceed 
until the screen has been refilled once. This feature 
allows users with high-speed terminals to fill the 
display screen, stop output with CTRL S, read the 
screen, and then continue with CTRL Q or CTRL A. 
(Typing CTRL C in this case also continues output.) 
Under the F/B Monitor, CTRL S has no special meaning if 
a SET TTY NOPAGE has been used. 

CTRL U 

Deletes the current input line and echoes as tU 
followed by a carriage return at the terminal. (The 
current line is defined to be all characters back to, 
but not including, the most recent line feed, CTRL C or 
CTRL Z.) 

CTRL Z 

Echoes tZ on the terminal and terminates input when 
used with the terminal device handler (TT). The CTRL Z 
itself does not appear in the input buffer. If TT is 
not being used, CTRL Z has no special meaning. 

RUBOUT 

Deletes the last character from the current line and 
echoes a backslash plus the character deleted. Each 
succeeding RUBOUT deletes and echoes another character. 

An enclosing backslash is printed when a key other than 
RUBOUT is typed. This erasure is done right to left up 
to the beginning of the current line. 


2.6.1 Foreground/Background Terminal I/O 

It is important to note that console input and output under F/B are 
independent functions; input can be typed to one job while output is 
printed by another• The user may be in the process of typing input to 
one job when the other job is ready to print on the terminal. In 
this case, the job which is ready to print interrupts the user 
and prints the message on the terminal; input control is not re¬ 
directed to this job, however, unless a CTRL B or CTRL F is explicitly 
typed. If input is typed to one job while the other has output 
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control, echo of the input is suppressed until the job accepting input 
gains output control; at this point all accumulated input is echoed. 

If the foreground job and background job are both ready to print 
output at the same time, the foreground job has priority. Output from 
the foreground job prints until a line feed is encountered, at which 
point output from the background job prints until a line feed is 
encountered, and so forth. 

When the foreground job terminates, control reverts automatically to 
the background job. 


2.6.2 Type-Ahead 

The monitor has a type-ahead feature which allows terminal input to be 
entered while a program is executing. For example: 

. R PIP 

*DT1:TRPE=PR: 

DT1:/L 

*13-FEB-74 

TAPE 78 13-FEB-74 

486 FREE BLOCKS 

While the first command line is executing, the second line (DT1:/L) is 
entered by the user. This terminal input is stored in a buffer and 
used when the first operation has completed. 

If a single CTRL C is typed while in this mode, it is put into the 
buffer. The program currently executing exits when a terminal input 
request needs to be satisfied. A double CTRL C returns control to the 
monitor immediately. 

If type-ahead input exceeds 80 characters, the terminal bell rings and 
no characters are accepted until part of the type—ahead buffer is used 
by a program or characters are deleted. No input is lost. Type-ahead 
is particularly useful in specifying multiple command lines to system 
programs, as shown in the preceding example. If a job is terminated 
by typing two CTRL C's, any unprocessed type-ahead is discarded. 


NOTE 

If type-ahead is used in conjunction 
with EDIT or BASIC, there is no terminal 
echo of the characters but they are 
stored in the buffer until a new command 
is needed. The characters are echoed 
only when actually used by the program. 


2.7 KEYBOARD COMMANDS 

Keyboard commands allow the user to communicate with the monitor. 
Keyboard commands can be abbreviated; optional characters in a 
command are delimited (in this section only) by braces. Keyboard 
commands require at least one space between the command and the first 
argument. All command lines are terminated by a carriage return. 
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All commands, with the exception of those described in Section 2.7.5, 
may be used under either the Single-Job or F/B Monitor. The commands 
described in Section 2.7.5 apply only to the F/B Monitor. 


NOTE 

Any reference made to "the background 
job" applies as well to the Single-Job 
Monitor, since the background job in a 
F/B system is equivalent to the 
single-job environment in its normal 
state. 


2.7.1 Commands to Control Terminal I/O (GT ON and GT OFF) 


GT ON/GT OFF 


The GT ON and GT OFF commands are used to enable cjid disable the 
scroller (VT—11 display hardware)• GT ON causes the display screen to 
replace the console as the terminal output device* Switch options 
allow the user to control the number of lines to appear on the screen 
and to position the first line vertically. Output appears on the 
display in the same format as it would on the console (i.e., output, 
text, and commands are displayed in the order in which they occur)• 
GT ON is not permitted in an 8K configuration. 

The form of the GT ON command is: 

GT ONj/L:nj>j/T:no¬ 
where : 

/L:n represents an optional switch setting indicating the 

number of lines of text to display; the suggested 
range is: 


12" screen 

(GT40, DEClab) 

l<=n<=37 

octal 

(31 

decimal) 

17" screen 
(GT44) 

l<=n<=50 

octal 

(40 

decimal) 


/T:n represents an optional switch setting indicating the 

top position of the scroll display; the suggested 
range is: 

12" screen l<=n<=1350 octal (744 decimal) 

(GT40, DEClab) 
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17" screen l<=n< ss 1750 octal (1000 

(GT44) decimal) 

If no switches are specified, a test for the screen size is performed 
and default values are automatically assigned as follows: 

12" screen /L:37 (31 decimal) 

(GT40, DEClab) /T:1350 (744 decimal) 

17" screen /L:50 (40 decimal) 

(GT44) /T:1750 (1000 decimal) 

Line length is always set to 72 for 12" screen and 80 for 17" screen. 
Once the display has been activated with the GT ON command, CTRL A, 
CTRL S, CTRL E and CTRL Q can be used to control scrolling behavior. 
These commands are described in Section 2.6. 

NOTE 

ODT is one exception to the use of GT 
ON. This system program has its own 
terminal handler and cannot make use of 
the display; output will appear only on 
the console terminal whenever ODT is 
running. 

The GT OFF command clears the display and resumes output on the 
teleprinter. The command format is: 

GT OFF 

If GT ON and GT OFF are used when no display hardware exists or when a 
foreground job is active, the ?ILL CMD? message is printed. 


2.7.2 Commands to Allocate System Resources 


DATE 


2.7,2.1 DATE Command - The DATE command enters the indicated date to 
the system. This date is then assigned to newly created files, new 
device directory entries (which may be listed with PIP), and listing 
output until a new DATE command is issued. 

The form of the command is: 

DAt|e| jdd-mmm-yyj* 

where dd-mmm-yy is the day, month and year to be entered, dd is a 
decimal number in the range 1—31; mmm is the first three characters of 
the name of the month, and yy is a decimal number in the range 73-99. 
If no argument is given, the current date is printed, 
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Examples: 

•DftTE 21-FEB-74 Enter the date 21-FEB-74 as the current 

system date, 

. DRT Print the current date, 

21-FEB-74 

If the date is entered in an incorrect format, the ?DAT? error 
message is printed. 


TIME 


2,7,2,2 TIME Command - The TIME command allows the user to find out 
the current time of day kept by RT-11 or to enter a new time of day. 
If no KW11-L clock is present on the system, the ?N0 CLOCK? error 
message is generated. If the time is entered in an incorrect format, 
the ?TIM? message is printed. 

The form of the command is: 

TIm|e| |hh:mm:ss} 

where hh:mm:ss represents the hour, minute, and second. Time is 
represented as hours, minutes, and seconds past midnight in 24-hour 
format (e.g., 1:25:00 P.M. is entered as 13:25:00). If any of the 
arguments are omitted, 0 is assumed. If no argument is given, the 
current time of day is output. 

Examples: 


.TIM 8:15:23 


Sets the time of day to 8 hours, 15 
minutes and 23 seconds. 


.TIM 

08:25:27 


Approximately 10 minutes later, the 
TIME command outputs this time. 


.TIME 18:5 


Sets the time of day to 18:05:00. 


Under the F/B Monitor, after the time reaches 24:00, the time and date 
will be reset when the user next issues a TIME command (or . GTIM pro¬ 
grammed request). Time and date are not reset under the Single-Job 
Monitor. Month and year are not updated under either monitor. 

The clock rate is initially set to 60-cycle. Consult the RT-11 System 
Generation Manual if conversion to a 50-cycle rate is necessary. 
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INITIALIZE 


2.7.2.3 INITIALIZE Command - The INITIALIZE command is used to reset 
several background system tables and do a general "clean-up" of the 

background area; it has no effect on the foreground job. In 
particular, this command makes non-resident those handlers which were 
not loaded (via LOAD), purges the background's I/O channels, disables 
CTRL 0, performs a hard reset, clears locations 40-53, resets the KMON 
stack pointer, and under the F/B monitor performs an .UNLOCK. 

Under the Single-Job Monitor a RESET instruction is done (see Chapter 
9). Under the F/B Monitor, I/O is stopped by entering each busy de¬ 
vice handler at a special abort entry point. 

The form of the command is: 



The INITIALIZE command can be used prior to running a user program, or 
when the accumulated results of previously issued GET commands (see 
Section 2.7.3.1) are to be discarded. 


Example 


Initializes system background job 


IN 

R r R 0 G 


ASSIGN 


2.7.2.4 ASSIGN Command - The ASSIGN command assigns a user-defined 
(logical) name as an alternate name for a physical device. This is 
especially useful when a program refers to a device which is not 
available on a certain system. Using the ASSIGN command, I/O can be 
redirected to a device which is available. Only one logical name can 
be assigned per ASSIGN command, but several ASSIGN commands (14 
maximum) can be used to assign different names to the same device. 
This command is also used to assign FORTRAN logical units to device 
names. 
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The form of the command is: 

ASs|ign| jjdevj:udevj 

where: 

dev is any standard RT-11 (physical) device name 

(refer to Table 2-2) with the exception of DK and 
SY. 

udev is a 1-3 character alphanumeric (logical) name to 

be used in a program to represent dev (if more 

than three characters are given, only the tirst 
three are actually used). DK and SY may be used 
as logical device names. 

: is a delimiter character (can be a colon, equal 

sign, and, if separating physical and logical 
devices, space). 

The placement of the delimiter is very important in the ASSIGN 
command; it must be placed exactly as shown in the following 
examples: 


ASSIGN DTI INP 


Physical device DTI 
logical device name 
reference to INP: 
device DTI: is used. 


is assigned the 
INP. Whenever a 
is encountered. 


ASSIGN DT3:DK Physical device name DT3 is assigned the 

default device name DK. Whenever DK is 

reterenced or defaulted to, DT3 is used. 
(Note that the initial assignment of DK 
is thus changed.) 


. ASSIGN LP=9 FORTRAN logical unit 9 becomes the 

physical device name LP. All references 
to unit 9 use the line printer for 
output. 

Assignment of logical names to logical names is not allowed. 

If only a logical device name is indicated in the command line, that 
particular assignment (only) is removed. Thus: 


.ASSIGN :S 

Deassigns the logical name 9 from its 
physical device (LP, in the case above). 

. ASSIGN =DK 

Removes assignment of logical name DK 
from its physical device (DT3, in the 
case above). 

If neither a physical device 
indicated, all assignments to 

name nor a logical device name is 
all devices are removed. 

. ASSIGN 

All previous logical device assignments 
are removed. 
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CLOSE 


2.7.2.5 CLOSE Command - The CLOSE command causes all currently open 
output files in the background job to become permanent files. If a 
tentative open file is not made permanent, it will eventually be 
deleted. The CLOSE command is most often used after CTRL C has been 
typed to abort a background job and to preserve any new files that job 
had open prior to the CTRL C; it has no effect on a foreground 30 b. 

The form of the command is: 

CLOUSE j- 

The CLOSE command makes temporary directory entries permanent. 

Example: 

r EDIT The Editor has a temporary 

* E W T E X T $ $ file open (TEXT ), which is 

♦IflBCD** preserved by .CLOSE. 

*~C 


CLOSE 


LOAD 


2.7.2.6 LOAD Command - The LOAD command is used to make a device 
handler resident for use with background and foreground jobs. 
Execution is faster when a handler is resident, although memory area 
for the handler must be allocated. Any device handler to be used by a 
foreground job must be loaded before it can be used. 


The form of the command is: 


LOA |d| dev |, dev=B j1, dev=F,... ^ 

where s 

dev represents any legal RT-11 device name. 

= represents a delimiter, denoting device ownership. 

B represents the background job. 


F represents the foreground job. 

The dev=F (and dev=B) construction is valid only under the 
Foreground/Background system. When used under the Single—Job Monitor, 
the ?ILL EV? error message occurs. 
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A device may be owned exclusively by either the foreground or 
background job. This may be used, for example, to prevent the I/O of 

intermixed on the same non-file 


The papertape punch belongs to the 
background job while the paper tape 
reader is available for use by 
either the background or foreground 
job; the line printer is owned by 
the foreground job. All three 
handlers are made resident in 
memory• 

Different units of the same random-access device controller may be owned I 
by different jobs. Thus, for example, DTI may belong to tne background 

while DT5 may belong to the foreground job. If no ownership is 
indicated, the device is available for public use. 

To change ownership of a device, another LOAD command may be used; it 
is not necessary to first UNLOAD the device. For example, if RK1 has 
been assigned to the foreground job as in the example above, the 
command: 

♦ LGA RK1-B 

reassigns it to the background job. 

The system unit of the system device cannot be assigned ownership, and 
attempts to do so will be ignored. Other units of the same type as 
the system device, however, can be assigned ownership. 

LOAD is valid for use with user-assigned names. For examples 

♦ ASSIGN RK2JXY 

♦ LOA XYF 


two different jobs from being 
structured device. For examples 

♦ LOAD PP=Bf F'Rf LF‘«F 


If the Single-Job, DECtape-based Monitor is being used, loading the 
necessary device handlers into memory can significantly improve the 
throughput of the system, since no handlers need to be loaded 
dynamically (in other words, they need not be loaded, as required, 
from the DECtape)• 


UNLOAD 


2.7.2•7 UNLOAD Command - The UNLOAD command is used to make handlers 
that were previously LOADed non-resident, freeing the memory they were 
using. 


2-21 


January 1976 






System Communication 


The form of the command is: 

UNL|oad| dev |,dev,. .. 

where: 


dev represents any legal RT-11 device name* 

UNLOAD clears ownership for all units of an indicated device type* 
For example, typing: 

. UNL RK2 

clears all units of RK* (A request to unload the system device 
handler clears ownership for any assigned units for that device, but 
the handler remains resident.) 

Any memory freed is returned to a free memory list and eventually 
reclaimed for the background job after the UNLOAD command is given. 
UNLOAD is not permitted if the foreground job is running. Such an 
action might cause a handler which is needed by the foreground job to 
become non-resident. 

Example: 


UNLOftD LP,PR The lineprinter and paper tape 

punch handlers are released and the 
area which they used is freed. 

A special function of this command is to remove a terminated 

foreground job and reclaim memory, since the space occupied by the 

foreground job is not automatically returned to the free memory list 

when it finishes. In this instance, the device name FG is used to 

specify the foreground job. For example: 

. UNL FG 

FG can be mixed with other device names. 

However, if, for example, DT2 has been assigned the name FG and loaded 
into memory as follows: 

♦ ASSIGN D1T2 1 FG 

* L OAD FG 

the command: 


* UNLOAD FG 

causes the foreground job, not DT2, to be unloaded. To unload DT2, 
this command must be typed: 

. UNLOftD DT2 


2-22 







System Communication 


SET 


2.7.2.8 SET Command - The SET command is used to change device 
handler characteristics and certain system configuration parameters. 

The form of the command is: 

SET dev:/ No\ option=value /,< NO >option=value,... 


represents any legal RT-11 physical device 

name (and in addition, TTY and USR). 

is the feature or characteristic to be 
altered. 

is a decimal number required in some cases. 

A space may be used in place of or in addition to the colon, equal 
sign, or comma. Note that the device indicated (with the exception of 
TTY and USR) must be a physical device name and is not affected by logical 

device name assignments which may be active. The name of the 

characteristic or feature to be altered must be legal for the 
indicated device (see Table 2-5) and may not be abbreviated. 

The SET command locates the file SYsdev.SYS and permanently modifies 
it. No modification is done if the command entered is not completely 
valid. If a handler has already been loaded when a SET command is 

issued for it, the modifications will not take effect until the 

handler is unloaded and a fresh copy called in from the system device. 

Table 2-5 lists the system characteristics and parameters which may be 

altered (those modes designated as "normal" are the modes as set in the 
distribution copies of the drivers): 


Table 2-5 

SET Command Options 


Device 

Option 

Alteration 

LP 

CR 

Allows carriage returns to be sent to the 

printer. The CR option should be set for any 
FORTRAN program using formatted I/O, to allow 
the overstriking capability for any line print¬ 
er, and when using the LS11 or LP05 line print¬ 
ers (since the last line in the buffer mav 
otherwise be lost) . This is the normal mode. 

LP 

NOCR 

Inhibits sending carriage returns to the line 

printer. The line printer controller causes a 
line feed to perform the functions of a carriage 
return, so using this option produces a signi¬ 
ficant increase in printing speed on LP11 print¬ 
ers . 

LP 

CTRL 

Causes all characters, including nonprinting con¬ 
trol characters, to be passed to the line printer. 
This mode may be used for LS11 line printers. 

(Other line printers will print space for control 
characters .) 


(continued on next page) 
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Table 2-5 (Cont.) 
SET Command Options 


Device 

Option 

Alteration 

LP 

NOCTRL 

Ignores nonprinting control characters. This is 
the normal mode. 

LP 

FORMO 

Causes a form feed to be issued before a 
request to print block zero. This is the 
normal mode. 

LP 

NOFORMO 

Turns off FORMO mode. 

LP 

HANG 

Causes the handler to wait for user 
correction if the line printer is not ready 
or becomes not ready during printing. This 
is the normal mode. 



New users should note that when expecting 
output from the line printer and it appears 
as though the system is not responding or is 
in an idle state, the line printer should be 
checked to see if it is on and ready to 
print. 

LP 

NOHANG 

Generates an immediate error if the line 
printer is not ready. 

LP 

LC 

Allows lower case characters to be sent to 
the printer. This option should be used if 
the printer has a lower case character set. 

LP 

NOLC 

Causes lower case characters to be translated 
to upper case before printing. This is the 
normal mode. 

LP 

WIDTH=n 

Sets the line printer width to n, where n is 
a number between 30 and 255. Any characters 
printed past column n are ignored. The NO 
modifier is not permitted. 

CR 

CODEan 

Modifies the card reader handler to use 
either the DEC 026 or the DEC 029 card codes 
(refer to Appendix H). n must be either 26 or 

29. The NO modifier is not permitted. 

CR 

CRLF 

Causes a carriage return/line feed to be 
appended to each card image. This is the 
normal mode. 

CR 

NOCRLF 

Transfers each card image without appending a 
carriage return/line feed. 

CR 

HANG 

Causes the handler to wait for user 
correction if the reader is not ready at the 
start of a transfer. This is the normal 
mode. 

CR 

NOHANG 

Generates an immediate error if the device is 
not ready at the start of a transfer. Note 
that the handler will wait regardless of how 
the option is set if the reader becomes "not 
ready" during a transfer (i.e., the input 
hopper is empty, but an end-of-file card has 
not yet been read). 
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Table 2-5 (Cont.) 
SET Command Options 


Device 


CR 


CR 


CR 


CR 

CT 


CT 


Option 


IMAGE 


NOIMAGE 


TRIM 


NOTRIM 

RAW 


NORAW 


Alteration 


Causes each card column to be stored as a 
12-bit binary number, one column per word. 
The CODE option has no effect in IMAGE mode. 
The format of the 12-bit binary number is: 

PDP-11 WORD 


15 14 13 12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 

UNUSED (ALWAYS 0) 

-1—-1_i 

ZONE 

12 

ZONE 

11 

ZONE 

0 

ZONE 

1 

ZONE 

2 

ZONE 

3 

ZONE 

4 

ZONE 

5 

ZONE 

6 

ZONE 

7 

ZONE 

8 

ZONE 

9 


This format allows binary card images to be 
read and is especially useful if a special 
encoding of punch combinations is to be used. 
Mark-sense cards may be read in IMAGE mode. 

Allows the normal translation (as specified 
by the CODE option) to take place; data is 
packed one column per byte. Invalid punch 
combinations are translated into the error 
character, ASCII "\" (backslash), which is 
octal code 134. This is the normal mode. 

Causes trailing blanks to be removed from 
each card read. It is not recommended that 
TRIM and NOCRLF be used together since card 
boundaries will be difficult to find. This 
is the normal mode. 

Transfers a full 80 characters per card. 

Causes the cassette handler to perform a 
read-after-write check for every record 
written, and retry if an output error 
occurred. if three retries fail, an output 
error is detected. 

Causes the cassette handler to write every 
record directly without reading it back for 
verification. This significantly increases 
transfer rates at the risk of increased error 
rates. Normal mode is NORAW. 


The following options, with the exception of HOLD/NOHOLD and" 

COPY/NOCOPY, are available in the Foreground/Background System only; 
HOLD/NOHOLD and COPY/NOCOPY are available in both systems. These 
options are not permanent, and must be reissued whenever the monitor 
is re-bootstrapped. They can be made permanent by modifying the moni¬ 
tor as described in Chapter 2 of the RT-11 Software Support Manual . 
(Note that the device specification is TTY, not TT, because the hand- 
ler itself is not changed.) 



Enables use of the auto-print mode of the 
VT50 copier option, if present. The com¬ 
mand is a no-op for any terminal other than 
the VT50, but a "] M character may be printed 
on the terminal. Consult the VT50 Video Ter¬ 
minal Programmer 1 s Manual for more infor¬ 
mation . 

Disables use of the auto-print mode of the 
VT50 copier option, if present. The command 
is a no-op for any terminal other than the 
VT50, but a "" " character may be printed on 
the terminal. This is the normal mode. 
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Table 2-5 (Cont.) 
SET Command Options 


Device 

option 

Alteration 

TTY 

CRLF 

Causes the monitor to issue a carriage 

return/line feed on the console terminal 
whenever it attempts to type past the right 
margin (as set by the WIDTH option). This is 
the normal mode. 

TTY 

NOCRLF 

Causes no special action to be taken at the 
right margin. 

TTY 

FB 

Causes the monitor to treat CTRL B and CTRL F 
characters as background and foreground 
program control characters and does not 
transmit them to the user program. This is 
the normal mode. 

TTY 

NOFB 

Causes CTRL B and CTRL F to have no special 
meaning. 



NOTE 



SET TTY NOFB is issued to KMON 9 
(which runs as a background job) 
and disables all communication with 
the foreground job. To enable 
communication with the foreground 
job, issue the command SET TTY FB. 

TTY 

FORM 

Indicates that the console terminal is 

capable of executing hardware form feeds. 

TTY 

NOFORM 

Causes the monitor to simulate form feeds by 
typing eight line feeds. This is the normal 
mode. 

TTY 

HOLD 

Enables use of the hold screen mode of op¬ 
eration for the VT50 terminal. The command 
is a no-op for any terminal other than the 
VT50, but a "[■ character may be printed on 
on the terminal. The command is valid for 

F/B and Single-Job Monitors. Consult the 
VT50 Video Terminal Programmer's Manual for 
more information. 

TTY 

NOHOLD 

Disables use of the hold screen mode of op¬ 
eration for the VT50 terminal. The command 
is a no-op for any terminal other than the 
VT50, but a H \" character may be printed on 
the terminal. This is the normal mode. 

TTY 

PAGE 

Causes the monitor to treat CTRL S and CTRL Q 
characters as terminal output hold and unhold 
flags, and does not transmit them to the user 
program. This is the normal mode. 


(continued on next page) 
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Table 2-5 (Cont.) 

SET Command Options 


Device 

Option 

Alteration 

TTY 

NOPAGE 

Causes CTRL S and CTRL Q to have no special 
meaning. 

TTY 

SCOPE 

Causes the monitor to echo RUBOUTs as 
backspace-space-backspace. This mode should 
be used when the console is a VT05/VT50 or 
when GT ON is in effect. 

TTY 

NOSCOPE 

Causes the monitor to echo RUBOUTs as 
backslash followed by the character deleted. 
This is the normal mode. 

TTY 

TAB 

Indicates that the console terminal is 

capable of executing hardware tabs. 

TTY 

NOTAB 

Causes the monitor to simulate tab stops 
every eight positions. The normal mode is 
NOTAB. VT05/VT50 terminals generally have 
hardware tabs. 

TTY 

WIDTH=n 

Sets the width of the console terminal to n 
positions, for the use of the CRLF option, n 
must be in the range 30-255 (decimal). The 
width is initially set to 72. 


The following variant of the SET command is used to prevent the 
background job from ever placing the USR in a swapping state (note 
that USR replaces a device specification in the command line)s 


SET USR |N0|SWAP 

This is useful when running on a DECtape based system, or when running 
a foreground job which requires the USR but has no memory allocated 
into which to read it* When the monitor is bootstrapped, it is in the 
SWAP condition, i.e., the background may place the USR in a swapping 
state via a SETTOP* 

The Single-Job Monitor behaves as though the following options are 
set: NOTAB, NOFORM, PAGE, NOCRLF, NOSCOPE, NOHOLD. 
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2.1.3 Commands to Manipulate Memory Images 


GET 


2.7.3.1 GET Command - The GET command (valid for use with a 
background job only) loads the specified memory image file (not ASCII 
| or object) into memory from the indicated device. 

The form of the GET command is: 

GE |t| devsfilnam.ext 


where: 


dev: 


filnam.ext 


represents any legal RT-11 device name. If a 
device is not specified, DK: is assumed. Note 
that devices MT and CT are not block-replaceable 
devices and therefore cannot be used in a GET 
command. 

represents a valid RT-11 filename and extension. 
If an extension is not specified , the extension 
.SAV is assumed. 


The GET command is typically used to load a program into memory for 
modification and/or debugging. The GET command can also be used in 
conjunction with the Base, Examine # Deposit, and START commands to 
test patches, and can be used with SAVE to make patches permanent. 
Multiple GETs can be used to combine programs. Thus: 


. GET GDT. SAV 
. GET PROG 


Loads ODT into memory 

Loads PROG.SAV into 
memory with ODT 


. START (ODTs starting address) 


Starts execution with ODT 
(see Chapter 8). 


The GET command cannot be used to load overlay segments of programs; 
it may only be used to load the root segment (that part which will not 
be overlaid; refer to Chapter 6, Linker). 

Multiple GETs can be used to build a memory image of several programs. 
If identical locations are required by any of the programs, the later 
programs overlay the previous ones. 

Examples: 


GET DT3: FILE!. SAV Loads the file FILE1.SAV into memory 

from DECtape unit 3. 


GET NAME1 Loads the file NAMEl.SAV from device DK. 
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BASE 


2•7.3.2 Base Command - The B command sets a relocation base. This 
relocation base is added to the address specified in subsequent 
Examine or Deposit commands to obtain the address of the location to 
be referenced. This command is useful when referencing linked modules 
with the Examine and Deposit commands. The base address can be set to 
the address where the module of interest is loaded. The form of the 
command is: 



where: 


location represents an octal address used as a base address for 
subsequent Examine and Deposit commands. 


NOTE 


A space must follow the B command 
even if an address is not specified 
(the B<space> command is equivalent 
to B 0). 


Any non-octal digit terminates an address. If location 
is odd, it is rounded down by one to an even address. 


The base is cleared whenever user program execution is initiated. 
Examples: 


. BA 


Sets base to 0 (A represents space). 


B 200 


Sets base to 200. 


B 201 


Sets base to 200. 
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EXAMINE 


2.7.3.3 Examine Command — The E command prints the contents of the 
specified location(s) in octal on the console terminal. The form of 
the Examine command is: 

E location m|-location nj- 

where s 

location represents an octal address which is added to the 
relocation base value (the value set by the B Command) 
to get the actual address examined. Any non-octal 
digit terminates an address. An odd address is 
truncated to become an even address. 

If more than one location is specified (location m-location n), the 
contents of location m through location n inclusive are printed. The 
second location specified (location n) must not be less than the first 
location specified, otherwise an error message is printed. If no 
location is specified, the contents of location 0 are printed. 
Examination of locations outside the background area is illegal. 

Examples: 


E 1000 Prints contents of location 1000 (added 

12? 4 01 to the base value if other than 0). 

.E 1081-1012 

12 7 4 01 0 0 7 6 2 4 1274 00 000000 000000 0000 0 0 

Prints the contents of locations 1000 
(plus the base value if other than 0) 
through 1013. 


DEPOSIT 


2.7.3.4 Deposit Command — The Deposit command deposits the specified 
value(s) starting at the location given. 

The form of the command is: 

D location=valuel/ value2,...valuen \ 
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where: 


location represents an octal address which is added to the 
relocation base value to get the actual address where 
the values are deposited. Any non-octal digit is 
accepted as a terminator of an address. 

value represents the new contents of the location. 0 is 

assumed if a value is not indicated. 

If multiple values are specified (valuel,•••,valuen), they are 
deposited beginning at the location specified. The DEPOSIT command 
accepts word or byte addresses but executes the command as though a 
word address was specified. An odd address is truncated by one to an 
even address. All values are stored as word quantities. 

Any character that is not an octal digit may be used to separate the 
locations and values in a DEPOSIT command. However, two (or more) 
non-octal separators cause 0 1 s to be deposited at the location 
specified (and those following). For examples 

.D 56,,, Deposits 0's in locations 56, 60, and 62. 

The user should be aware of situations like the above, which causes 
system failure since the terminal vector (location 60) is zeroed. 

An error results when the address specified references a location 
outside the background job's area. 

Examples: 


. D 1000=3705 
. B 1000 
. D 1500=2503 
. B 0 


Deposits 3705 into location 1000 
Sets relocation base to 1000 
Puts 2503 into location 2500 
Resets base to 0 


SAVE 


2.7.3.5 SAVE Command - The SAVE command writes specified user memory 
areas to a named file and device in save image format. Memory is 

written from location 0 to the highest memory address specified by the 
parameter list or to the program high limit (location 50 in the system 
communication area). 

The SAVE command does not write the overlay segments of programs; it 
saves only the root segment (refer to Chapter 6, Linker). 

The form of the command is: 

SAv|e| devsfilnam.ext ^parameters| 

where: 

devs represents one of the standard RT-11 block-replaceable 

device names. If no device is specified, DK is 
assumed. 
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file.ext represents the name to be assigned to the file being 
saved. If the file name is omitted, an error message 
is output. If no extension is specified, the extension 
•SAV is used. 

parameters represent memory locations to be saved. RT-11 transfers 
memory in 256-word blocks beginning on boundaries that 
are multiples of 256(decimal). If the locations speci¬ 
fied make a block of less than 256 words, enough addi¬ 
tional locations are transferred to make a 256-word block. 

Parameters can be specified in the following format: 
areal,area2-arean 


where: 


areal represent an octal number (or numbers 

area2-arean separated by dashes). If more than one number 

is specified, the second number must be 
greater than the first. 


The start address and the Job Status Word are given the default value 
0 and the stack is set to 1000. If the user wants to change these or 
any of the following addresses, he must first use the DEPOSIT command 
to alter them and then SAVE the correct areas: 


Area 


Location 


Start address 40 
Stack 42 
JSW 44 
USR address 46 
High address 50 
Fill characters 56 


If the values of the addresses are changed, it is the user's 
responsibility to reset them to their default values. See Chapter 9 
for more information concerning these addresses. 


Examples: 


.SRVE FI LEI 10000-11000,14000-14100 

Saves locations 10000(8) through 
11777(8) (11000 starts the first word of 

a new block, therefore the whole block, 
up to 12000, is stored) and 14000(8) 
through 14777(8) on DK with the name 
FILE1.SAV. 

.SRVE DTI:NAM.NEW 10000 

Saves locations 10000 through 10777 on 
DTI: with the name NAM.NEW. 

. D 44 :20000 

. SRV SV.-PRHM 1000-5777 

Sets the reenter bit in the JSW and 
saves locations 1000 through 5777. 
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2.7.4 Commands to Start a Program 


RUN 


2.7.4.1 RUN Command - The RUN command (valid for use with a 
background job only) loads the specified memory image file into memory 
and starts execution at the start address specified in location 40. 
Under the F/B system, 10 words of user stack area are required to 
start a user program, and the stack address (location 42) must be 
initialized to some part of memory where these 10 words will not 
modify it. 

The form of the command is: 

Ru|n| devsfilnam.ext 

where: 

dev: is any standard device name specifying a 

block-replaceable device. If dev: is not specified, 
the device is assumed to be DK. Note that devices MT 
and CT are not block-replaceable devices and 
therefore cannot be used in a RUN command. 

filnam.ext is the file to be executed. If an extension is not 
specified, the extension .SAV is assumed. 

The RUN command is equivalent to a GET command followed by a START 
command (with no address specified). 


NOTE 

If a file containing overlays is to be RUN from 
a device other than the system device, the handler 
for that device must be loaded (see Section 2.7.2.6) 
before the RUN command is issued. 

Examples: 

.RUN DTI: SRC H. SflV Loads and executes the file SRCH.SAV 

from DTI. 

.RUN PROG Loads PROG.SAV from DK and executes the 

program. 

.GET PRGG1 Loads PROG1.SAV from device DK without 

executing it. Then combines PROG1 and 

.RUN F'R0G2 PROG2.SAV in memory and begins execution 

at the starting address for PROG2. 
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2.7.4.2 R Command - This command (valid for use with the background 
job only) is similar to the RUN command except that the file specified 
must be on the system device (SY:). 

The form of the command is: 

R filnam.ext 

No device may be specified. If an extension is not given, the 
extension .SAV is assumed. 

Examples: 


.R XVZ.SRV Loads and executes XYZ.SAV from SY. 

. R src Loads and executes SRC.SAV from SY. 


START 


2.7.4.3 START Command - The START command begins execution of the 
program currently in memory (i.e., loaded via the GET command) at the 
specified address. START does not clear or reset memory areas. 

The form of the command is: 

St|art| /addressj- 

where: 


address is an octal number representing any 16-bit 
address. If the address is omitted, or if 0 is 
given, the starting address in location 40 will be 
used. 

If the address given does not exist or is not an even address, a trap 
to location 4 occurs. In this case a monitor error message appears. 
If no address is given, the program's start address from location 40 
is used. 
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Examples: 

♦ GET FILE*1 Loads FILE.l into memory and starts execution 

* START 1000 at location 1000. 


♦GET FILEA 

♦ GET FILES 

* ST 


Loads FILEA.SAV, then combines FILEA.SAV with 
FILEB.SAV and starts execution at FILEB 9 s 
start address. 


REENTER 


2.7.4.4 REENTER Command - The REENTER command starts the program at 
its reentry address (the start address minus two). REENTER does not 
clear or reset any memory areas and is generally used to avoid 
reloading the same program for repetitive execution. It can be used 
to return to a program whose execution was stopped with a CTRL C. 

The form of the command is: 

re-enter*. 

If the reenter bit (bit 13) in the Job Status Word (location 44) is 
not set, the REENTER command is illegal. 


For most system programs, the REENTER command restarts the program at 
the command level. 


If desired, the reentry point in a user program can branch to a 
routine which initializes the tables and stack, fetches device 
handlers etc., and then continue normal operation. 


Example: 

. R PIP 
*/F 

M0NITR. SVS 

[directory prints] 

• ({c typed) 


CTRL C interrupts the PIP 
directory listing and transfers 
control to the monitor level. 
REENTER returns control to PIP. 


REENTER 

* 


2.7.5 Commands Used Only in a Foreground/Background Environment 

It is important to note that in order to control execution of a 
foreground job, the commands in this section must be typed to KMON, 
which is running as the background job. Thus, for example, to SUSPEND 
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the foreground job, the user must be sure he is directing input to 
KMON as follows: 


F> 

(tB typed) 

B> 

R PIP 


*~C 


# SUSPEND 


Foreground job is running. Control 
is redirected to the background job 
and PIP is called (the foreground 
is still active)• CTRL C stops PIP 
and starts KMON, The foreground 
job is suspended, (See Section 
2 . 7 . 5 . 2 .) 


FRUN 


2,7,5,1 FRUN Command - The FRUN command is used to initiate 
foreground jobs, FRUN will only run relocatable files produced with 
the Linker /R switch (using the Linker supplied with RT-11, Version 
2)• Any handlers used by a foreground job must be in memory. 


The form of the command is: 

FRu|n| dev:file.extj/N:njj/S:nj|/P} 

where: 

dev: represents a block replaceable RT-11 device. If 

dev: is not specified, DK: is assumed. 

file.ext represents the job to be executed. The default 

extension for a foreground job is .REL. 


/N:n or /Nln represents am optional switch used to allocate n 
words (not bytes) over and above the actual 
program size. (If running a FORTRAN program, a 
special formula is used to determine n. Refer to 
Appendix G for this information.) 

/S:n or /Sin represents am optional switch used to allocate n 
words (not bytes) for stack space. Normally, 
stack space is set by default to 128 words and is 
placed in memory below the program. To change the 
stack size, use /S:nj the stack is still placed in 
memory under the program. To relocate the stack 
area, use an .ASECT (see Chapter 5) to define the 
start of the user stack in location 42. This 
overrides the /S switch. 


/P represents an optional switch (at the end of the 

FRUN command) for debugging purposes. When the 
carriage return is typed, FRUN prints the load 
address of the program, but does not start the 


2-36 




System Communication 


program. The foreground job must be explicitly 
started with the RSUME command (see Section 
2.7.5.3). For example: 

. FRUN DfiTfi/P 
LORDED RT 125444 


If ODT is used with the foreground job, this 
feature provides the means for determining where 
the 30 b actually was loaded. 

The program is started when the RSUME command is 
given, allowing the programmer to examine or 
modify the program before starting it. 



Examples: 


.FRUN FI 


Runs program FI.RED stored on device DK. 
Runs F2.REL which is on DTI. 


.FRU DTI:F2 


SUSPEND 


2.7.5.2 SUSPEND Command - The 
execution of the foreground job. 

The form of the command is: 


SUSPEND command is used to stop 




discussion of completion routines). 
resumed only from the keyboard. 

Example: 


Execution of the job can be 


.SUSPEND Suspends execution of the foreground job currently 
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, 7 c 3 rsume C omman d - The RSUME command is used to resume execution 
H toi foSSSundTjSb where it was suspended. Any completion routines 
which were scheduled while the foreground was suspended are entered at 
this time. 

The form of the command iss 

rsu|me| 

No arguments are required. 


Example: 


. RSU 


Resumes execution of the foreground job 
suspended. 


currently 


2.8 MONITOR ERROR MESSAGES 

The following error messages indicate fatal conditions that can occur 
during system boot: 

Meaning 

An I/O error occurred during system boor. 

No bootstrap has been written on volume. 

No monitor exists on volume being booted. 

There is not enough memory for the system 
being booted (e.g., attempting to boot 
F/B into 8K). 

The following error messages are output by the Keyboard Monitor. 


Message 

7B-I/0 ERROR 

7B-N0 BOOT ON VOLUME 

7B-N0 MONITR.SYS 
7B-N0T ENOUGH CORE 


Message 

/adDR? 

7DAT? 

7ER RD OVLY? 


F? 

?F ACTIVE? 

7FIL NOT FND? 

7FILE? 

January 1976 


Meaning 

Address out of range in E or D command. 

The DATE commemd argument was illegal, 
or no argument was given and the date 
has not yet been set. 

An I/O error occurred while reading a 
KMON overlay to process the current 
command. This is a serious error, 
indicating that the system file 
MONITR.SYS is unreadable. 

A CTRL F was typed under the F/B monitor 
and no foreground job exists. 

Neither FRUN nor UNLOAD may be used when 
a foreground job already exists and is 
active. 

File specified in R, RUN, GET, or FRUN 
commemd not found. 

No file named where one is expected. 
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Message 

?ILL CMD? 

?ILL DEV? 

?N0 CLOCK? 

?NO FG? 

?OVR COR? 

7PARAMS? 

?REL FIL I/O ER? 

?SV FIL I/O ER? 


Meaning 


Illegal Keyboard Monitor command or 
command line too long. 

Illegal or nonexistent device, or an 
attempt was made to make a .device 
handler resident for use with a 
foreground job (dev=F) when the 
Single-Job Monitor was running. 

No KW11L clock is available for the TIME 
command. 

A SUSPEND, RSUME, or UNLOAD FG command 
was given, but no foreground job was in 
memory. 

Attempt to GET or RUN a file that is too 
big. 

Bad parameters were typed to the SAVE 
command. 

Either the program requested is not a 
REL file or a hardware error was 
encountered trying to read or write the 
file. 

I/O error on .SAV file in SAVE (output) 

or R, RUN, or GET (input) command. Pos¬ 
sible errors include end-of-file, hard 
error, and channel not open. 


?SY I/O ER? 
?TIM? 


I/O error on system device (usually 
reading or writing swap area). 

The TIME command argument was illegal. 


The following messages are output by the RT-11 Resident Monitor when 
an unrecoverable error has occurred. Control passes to the Keyboard 
Monitor. The program in which the error occurred cannot be restarted 
with the RE command. To execute the program again, use the R or RUN 
command. 


The format for fatal monitor error messages iss 


?M-text PC where PC is the address+2 of the 

location where the error occurred. 

Note that ?M errors can be inhibited in certain cases by the use of 
the .SERR macro; see Chapter 9 for details. 


Message Meaning 

?M—BAD FETCH Either an error occurred while reading 

in a device handler from SY, or the 
address at which the handler was to be 
loaded was illegal. 
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?M-DIR 10 ERR 

An error occurred doing I/O in the 
directory o f a device (e.g., .ENTER on a 
write-locked device). 

?M-DIR OVFLO 

No more directory segments were 
available for expansion (occurs during 
file creation (.ENTER)). 

?M—DIR UNSAFE 

onl y» this message may appear in 
addition to any of the other diagnostics 
listed in this section. it indicates 
that the error occurred while the USR 
was updating a device directory. One or 
more files on that device may be lost. 

?M-FP TRAP 

A floating-point exception trap 

°^f red ' and the user Program had no 
•SFPA exception routine active (see 
Chapter 9). 

7M-ILL ADDR 

Under the F/B Monitor, an address 
specified in a monitor call was odd or 
was not within the job's limits. 

7M-ILL CHAN 

A channel number was specified which was 
too large. 

7M-ILL EMT 

An EMT was executed which did not exist; 
i*e«, the function code was out of 
bounds. 

7M-ILL USR 

The USR was called from a completion 
routine• This error does not have a 
soft return (i.e., .SERR will not 
inhibit this message; see Chapter 9). 

7M-N0 DEV 

A READ/WRITE operation was tried but no 
device handler was in memory for it. 

7M-0VLY ERR 

A user program with overlays failed to 
successfully read an overlay. 

7M-SWAP ERR 

A hard I/O error occurred while the 

system was attempting to write a user 
program to the system swap blocks. 

This is usually caused by a write- 
locked system device. Under the Single- 
Job Monitor, this may cause the system 
to halt. 

VM-SYS ERR 

An I/O error occurred while trying to 
read KMON/USR into memory, indicating 
that the monitor file is situated on the 
system device in an area that has 
developed one or more bad blocks. The 
monitor prints the message and loops 
trying to read KMON. The message is a 
warning that the system device is bad. 
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If, after several seconds, it is 
apparent that attempts to read KMON are 
failing, halt the processor. It may be 
impossible to boot the volume because of 
the bad area in the monitor file. Use 
another system device to verify the bad 
blocks and follow the recovery procedures 
described in section 4.2.12.1 of Chapter 

?M—TRAP TO 4 The job has referenced illegal memory 

?M—TRAP TO 10 or device registers, an illegal instruc¬ 

tion was used, stack overflow occurred, 
a word instruction was executed with an 
odd address, or a hardware problem caused 
bus time-out traps through location 4. 


If CSI errors occur and input was from the console terminal, an 
message is printed on the terminal. 


error 


Message 
?DEV FUL? 
?FIL NOT FND? 
?ILL CMD? 

?ILL DEV? 


Meaning 

Output file will not fit. 

Input file was not found. 

Syntax error. 

Device specified does not exist. 


2.8.1 Monitor HALTS 


F/B and t h 1 2 • *2 *** RT_11 V02 mon itors, one each in 

t/B and Single-Job. The Single-Job Monitor will halt only if i/o 

errors occur during swap operations to the system device, if the S/J 
Monitor halts, look for a write—locked system device. 


The F/B Monitor will halt if 
occurs while the system is 
it cannot recover. If the 
non-existent devices, traps 
user-corrupted queue elements 


a trap to location 4 occurs or if I/o 
performing critical operations from which 
F/B Monitor halts, look for use of 
from interrupt service routines, or 


The monitor halts can be detected by their address, which is 
memory, above the resident base address (location 54). 


high 


in 


When a monitor halt occurs, do not 
pressing CONTinue on the processor; 


attempt to restart the system by 
the system must be rebooted. 
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CHAPTER 4 


PERIPHERAL INTERCHANGE PROGRAM (PIP) 


The Peripheral Interchange Program (PIP) is the file transfer and 
maintenance utility for RT-11. PIP is used to transfer files between 
any of the RT-11 devices (listed in Table 2-2) , merge and delete files 
from these devices, and list, zero, and compress device directories. 


4.1 CALLING AND USING PIP 
To call PIP from the system device type s 
R PIP 

in response to the dot printed by the Keyboard Monitor. The Command 
String Interpreter prints an asterisk at the left margin of the 
terminal and waits to receive a line of filenames and command 
switches. PIP accepts up to six input filenames and three output 
filenames; command switches are generally placed at the end of the 
command string but may follow any filename in the string. There is no 
limit to the number of switches which may be indicated in a command 
line, as long as only one operation (insertion, deletion, etc.) is 
represented. 

Since PIP performs file transfers for all RT-11 data formats (ASCII, 
object, and image) there are no assumed extensions for either input or 
output files; all extensions, where present, must be explicitly 
specified. 

Following completion of a PIP operation, the Command String 
Interpreter prints an asterisk at the left margin of the teleprinter 
and waits for another PIP command line. Typing CTRL C at any time 
returns control to the Keyboard Monitor. To restart PIP, type R PIP 
or the REENTER command in response to the monitor's dot. 


4.1.1 Using the "Wild Card" Construction 

PIP follows the standard file specification syntax explained in 
Section 2.5. (Chapter 2) with one exception: the asterisk character 
can be used in a command string to represent filenames or extensions. 
The asterisk (called the "wild card") in a file specification means 
all . For instance, "*.MAC" means all files with the extension .MAC. 
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regardless of filename. "FORTN.*" means all files with the filename 
FORTN regardless of extension. "*.*" means all files, regardless of 
name or extension. 


The wild card character is legal in the following cases only (switches 
are explained in the next section): 

1. Input file specification for the copy and multiple copy 
operations (i.e., no switch, /I, /B, and /A). 

2. File specification for the delete operation (/D). 

3. Input and output file specifications for the rename operation 

</R). 

4. Input and output file specifications for the multiple copy 
operation (/X). 

5. Input file specifications for the directory list operations 
(/L, /E, /F). 


Operations on files implied by the wild card asterisk are performed in 
the order in which the files appear in the directory. System files 
with the extension .SYS and files with bad blocks and the extension 
.BAD are ignored when the wild card character is used unless the /Y 
switch is specified. 

Examples: 

**. BRK,'D Causes all files with the extension .BAK 

(regardless of their filenames) to be 
deleted from the device DK. 


**. TST = *. BRK/R 


#RK1 1 * ♦ fc/X/Y--# ♦ * 


##.MAC iM .OBJ/L 


Renames all files with a .BAK extension 
(regardless of filenames) so that these 
files now have a .TST extension 
(maintaining the same filenames)« 

Transfers all files, including system 
files, (regardless of filename or 
extension) from device DK to device RK1. 

Lists all files with .MAC and .OBJ 
extensions. 


4.2 PIP SWITCHES 

The various operations which can be performed by PIP are summarized in 
Table 4—1. If no switch is specified, PIP assumes the operation is a 
file transfer in image (/I) mode. Detailed explanations of the 
switches follow the table. 
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Table 4-1 
PIP Switches 


Switch 

Section 

Explanation 

/A 

4.2.2 

Copies file(s) in ASCII mode; ignores nulls and 
rubouts; converts to 7-bit ASCII; CTRL Z (32 octal) 
treated as logical end-of-file on input. 

/B 

4.2.2 

Copies files in formatted binary mode. 

/c 

4.2.2 

May be used in conjunction with another switch to 
cause only files with current date (as designated 
using the monitor DATE command) be included in 
the specified operation. 

/D 

4.2.4 

Deletes file(s) from specified device. 

/E 

4.2.6 

Lists the device directory including unused spaces 
and their sizes. An empty space on a cassette or 
magtape directory represents a deleted file. 
Sequence numbers are listed for cassettes. 

/F 

4.2.6 

Prints a short directory (filenames only) of the 
specified device. 

/G 

4.2.2 

Ignores any input errors which occur during a file 
transfer and continues copying. 

/I or no 
switch 

4.2.2 

Copies file(s) in image mode (byte by byte). This 
is the default switch. 

/K 

4.2.12 

Scans the specified device and types the absolute 
block numbers (in octal) of any bad blocks on the 
device. 

A 

4.2.6 

Lists the directory of the specified device, 
including the number of files, their dates, and 
the number of blocks used by each file. Sequence 
numbers are listed for cassettes. 

/Msn 

4.2.1 

Used when I/O transfers involve either cassette or 
magtape, n represents the numeric position of the 
file to be accessed in relation to the physical 
position of the cassette or magtape on the drive. 

If n is positive, the tape spaces forward from its 
current position until either the filename or the 
nth file is found; if n is negative, the tape is 
rewound first, and then it spaces forward until 
either the filename or the nth file is found. If 
n is 0 (or not indicated) the tape is rewound and 
searched for the filename. For wild card 
operations, specification of /M with a positive 
argument will prevent the tape from rewinding 
between each file involved in the operation. 

/N:n 

4.2.7 

Used with /Z to specify the number of directory 
segments (n) to allocate to the directory. 

/o 

4.2.10 

Bootstraps the specified device (DTO, RKn, RF, DPn, 
DSn, DXn only). 
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Table 4-1 (Cont.) 
PIP Switches 


Switch 

Section 

Explanation 

/Q 

4.2.2 

When used in conjunction with another PIP 
operation, causes PIP to type each filename which 
is eligible for a wild card operation and to ask 
for a confirmation of its inclusion in the 
operation. Typing a "Y" causes the named file to 
be included in the operation; typing anything 
else excludes the file. The command line is not 
processed until the user has confirmed each file 
in the operation. 

/R 

4.2.5 

Renames the specified file. 

/s 

4.2.8 

Compresses the files on the specified directory 
device so that free blocks are combined into one 

* 


area. 

/T 

4.2.4 

Extends number of blocks allocated for a file. 

/u 

4.2.9 

Copies the bootstrap from the specified file into 
absolute blocks 0 and 2 of the specified device. 

A 

4.2.11 

Types the version number of the PIP program being 
used. 

A 

4.2.6 

Includes the absolute starting block and any extra 
directory words in the directory listing for each 
file on the device (numbers in octal). Used with 
/F, /L, or /E. 

/x 

4.2.3 

Copies files individually (without concatenation)• 

A 

4.2.2 

Causes system files and .BAD files to be operated 
on by the command specified. Attempted 
modifications or deletions of .SYS or .BAD files 
without /Y are not done and cause the message ?N0 
SYS ACTION? to be printed. 

/Z:n 

4.2.7 

Zeroes (initializes) the directory of the 
specified device? n is used to allocate extra 
words per directory entry. When used with /N, the 
number of directory segments for entries may be 
specified. When used with cassette, /Z writes a 
sentinel file at the beginning of the tape? with 
magtape, /Z writes a volume label followed by a 
dummy file followed by double tape marks 
indicating logical end-of-tape. 


4.2.1 Operations Involving Magtape or Cassette 

PIP operations involving cassette and magtape devices are handled 
somewhat differently than other RT-11 devices , because of the 
sequential nature of these devices. The last file on a cassette or 
magtape (the logical end-of-tape) is specially formatted so that it 
marks the end of current data and indicates where new data may begin 
(double end-of-file for magtape , sentinel file or physical end-of-tape 
for cassette). Therefore , operations which designate specific block 
lengths (such as /T and /N) are meaningless, and unused spaces on the 
tape (resulting from file deletions) cannot be filled. 
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PIP operations which are legal using cassette and magtape (including 
the bootable magtape on which the system may have been distributed) 
include the following: /A, /B, /D, /E, /F, /G, /I, /L, /M, /Q, /V, 

/W f /X, /Y, and /Z. Usually the device (CT or MT) is rewound each 
time an operation is performed. Since there is no inclusive directory 
at the beginning of the tape the only way to access a file is to 
search the tape from the beginning until it is found. However, the 
/M:n switch is available for situations where it is not necessary or 
desirable to rewind the tape before each operation. If the argument 
(n) is positive, the operation indicated will not rewind the tape 
first, but will space forward until it finds either the nth file, the 
filename indicated in the command line, or the logical end-of-tape, 
whichever occurs first. If the argument is negative, the cassette or 
magtape will be rewound first and then spaced forward until the file¬ 
name (or nth file, or logical end-of-tape) is found. Thus: 

/M:l means suppress rewind, begin operation at 

current position. 

/M:-l means rewind tape and access the first file 

on it. 

Remember that when /Msn is used, n is interpreted as an octal number. 
/MJn must be used if it is intended that n represent a decimal number. 

For example, assume the directory of a cassette on unit 1 iss 

17-JUL-74 
FILE .1 
FILE .2 
FILE .3 
FILE .4 
FILE .5 
5 FILES, 2 
* 

and the last PIP operation involved FILE.4, leaving the cassette 
positioned at the end of FILE.4. To access FILE.2, the next operation 
(for example, deleting FILE.2) could use the /M construction: 

*CT1:DUM/M:-2/D 

In this case, the cassette rewinds first, then spaces forward from its 
current position to the second file in sequence and deletes it. (In a 
delete operation, the dummy filename is necessary; otherwise, a 
non-file structured delete is performed and the tape is zeroed. See 
Section 4.2.4). 

Another useful application of the /M switch involves a case where a 
number of files are to be created on a magtape or cassette. Using the 
construction: 

*MT : * */X=FILE. 1, FILE. 2 . . . /M : 1000 

prevents a rewind from occurring before each new file is created on 
the tape. Normal operation (when creating a new file on magtape or 
cassette) is to rewind, then search the tape for the logical end. If 
a file with the same name as the one being created is encountered, it 
is deleted and the new file is opened at the logical end of the tape. 
The /M:1000 command first causes the tape to space forward until it 
reaches the logical end-of-tape, (assuming less than 1000 (octal) 
files on the tape), at which point the next file is entered, and so 
on. If the tape were already positioned at the end of the tape, an 


0 5-MAY-74 

0 5-MAY-74 
1 13-MAY-7 4 

1 28-JUN-74 
0 17-JUL-74 
BLOCKS 
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/M:l would suffice to cause the new file to be written there. Note 
that creation of a new file with the /M switch can result in several 
files with the same name on the same tape; those files occurring 
before the tape position are not searched for duplication prior to the 
creation of the new file, 

RT-11 magtapes sometimes contain a dummy file at the beginning of the 
tape, which is written when the tape is initialized with the /Z 
switch. This file shows up in extended directories (/E) as an 
<UNUSED> entry in the first file position. Deleted files on magtape 
or cassette do not show up in /F or /L directory listings, but must 
always be considered when the /Msn switch is used. Care must always 
be taken to use a /E directory when counting file position prior to 
using that position as an /M:n argument; <UNUSED> files must be 
counted as files on the tape. 


For example: 


. R PIP 

*MT0:/E 

ll-SEP-74 


< 

UNUSED > 

0 


ft 

. MftC 

40 

ll-SEP-74 

B 

. MftC 

15 

ll-SEP-74 

< 

UNUSED > 

2 


D 

. MftC 

2 

ll-SEP-74 

3 

FILES, 57 

BLOCKS 

*MT0:/L 



11 

-SEP-74 



ft 

. MftC 

40 

ll-SEP-74 

B 

. MftC 

15 

ll-SEP-74 

D 

. MftC 

2 

ll-SEP-74 


3: FILES, 57 BLOCKS 


Extended directory: shows 
absolute file positions. 


Normal directory; does 
not accurately display 
file positions. 


If the user wished to access file A.MAC on the magtape in the example 
above, /M:-2 must be used (/M:-l would access the first empty file). 
Likewise, B.MAC is accessed with /M:-3. Rewind can also be suppressed 
for cassette and magtape as input devices by specifying a very large 
number in conjunction with wild card transfers from magtape or 
cassette. 


**, *-MT0 : *. */ M: 20@U/X 


This transfers all files from MTO: to DK: without rewinding between 
each file. The argument 2000 is an arbitrarily large number; any 
number larger than the actual number of files on the tape will 
suffice. 


The most common method for spacing to the end of the tape is: 

*DUMMV=MT0:DUMMVVM:2000 
?FIL NOT FND? 

where DUMMY is a file name which does not exist on the tape. Note 
that an error message is printed when the end of the tape is reached. 
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Directory listings of magtapes include the length of each file in 
256(decimal) word blocks. In cassette directories, however, sequence 
numbers rather than block numbers are printed. Sequence numbers 
indicate the sequential ordering of a file in cases where it has been 
continued on more than one cassette. In the example cassette 

directory listing (at the beginning of this section), the numbers in 
the middle column represent sequence numbers; both FILE.3 and FILE.4 
are the second segments of continued files. All files on cassette are 
initially assigned a sequence number of 0 (meaning this is the first 
segment of the cassette file, not that the file has no length). The 
sequence number is automatically updated whenever the file must be con¬ 
tinued as a result of a full cassette. 

During I/O transfer operations involving cassette, if the cassette is 
full before the transfer has finished, the message: 

CTn: PUSH REWIND OR MOUNT NEW VOLUME 

is printed; n represents the number of the drive (0 or 1) on which 
the current cassette is mounted. If the cassette rewind button is 
subsequently pushed, an error message is typed (IN or OUT ERR) and the 
tape is rewound. 

To continue an output operation, mount a new cassette (which has been 
properly formatted as described in Section 4.2.7) on the same drive. 
The new cassette is rewound automatically and a file is opened on it 
under the same name and extension; the sequence number in its 
directory is updated to reflect the continuation, and the transfer 
continues. 

If the message occurs during an input operation, mount the cassette 
containing the continued portion of the file on the drive; the 
cassette is rewound first. PIP then looks for a file with the same 
name and extension and the proper sequence number and continues the 
input operation. The message is repeated if the next segment is not 
found. 

For example: 

*CT0:FILE. RGR=DT 1: fiSC. MRC, DK : BflLOR. MRC/fl 
CT0 : PUSH REWIND OR MOUNT NEW VOLUME 

This copies in ASCII mode the file ASC.MAC from DECtape 1 and 
BALOR.MAC from device DK and combines them under the name FILE.AGA on 
CTO. The cassette runs out of room and requests that a new one be 
mounted. The operation continues automatically when the second 
cassette has been mounted. 

A directory of the second cassette in the above operation is next 
requested; note that the sequence number of FILE.AGA is 1, signifying 
it is the second part of a continued file. 

*CT0:/L 
23-MAY-7 4 

TRA .BIN 0 16-F EB-74 

FILE .AGA 1 23-MAY-74 

2 FILES* 1 BLOCKS 
* 

(The number of blocks in a cassette directory simply represents the 
total of sequence numbers in the directory.) 

Any cassette mounted in response to a continuation message MUST have 
been previously initialized at some time as described in Section 
4.2.7. 
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If a full cassette is mounted or an attempt is made to access some 
file on it that does not exist, the continuation message recurs. 

The operation may be continued by mounting another cassette. 

Note that if an attempt is made to access a file which has a non-zero 
sequence number (during some operation which is not a continuation of 
an operation), the file will not be found. 

To copy multiple files to a cassette using a wild card command, use 
the following: 


*CTn:*.*=DEV:*.*/X/M:1 (rewind is inhibited) 

Continue to mount new cassettes in response to the PUSH REWIND OR 
MOUNT NEW VOLUME message. Do not abort the process at any time (using 
two CTRL Cs) since continuation files may not be completed and no sen¬ 
tinel file will be written on the cassette. 

To read multiple files from a cassette, use the following: 

*DEV:*.*=CTn:*.*/X/M:1000 (rewind is inhibited) 

Whenever a continued volume is detected, the PUSH REWIND OR MOUNT NEW 
VOLUME message will appear, until the entire file has been copied (as¬ 
suming that each sequential cassette is mounted in response to each oc¬ 
currence of the message). Whenever PIP has copied the final section 
of a continued file, it will return to command level. To copy the 
remaining files on that cassette, reissue the command: 

*DEV:*.*=CTn:*.*/X/M:1000 


Repeat the process as often as necessary to copy all files. Do not 
abort the process at any time (using two CTRL Cs) since continuation 
files may not be completed. 

If the end of a tape is reached during a magtape I/O operation, an IN 
or OUT ERR message is printed. In the case of an output operation, 
the magtape backspaces and deletes the partial file by writing logical 
end of tape over the file's header label. The operation must then be 
repeated using another magtape. 

If CTRL C is typed during any output operation to cassette or magtape, 
an end-of-tape or sentinel file is not written on the tape first. 
Consequently , no future enters may occur to the tape unless one of two 
recovery procedures is followed: 

!• Transfer all good files from the bad tape to another tape and 
zero the bad tape in the following manner: 

*devl:*.*/X=dev0:filel,file2,...filen/M:100 0 
*dev0:/Z 

devO:/Z ARE YOU SURE ? 

This causes a logical end-of-tape to be written onto the bad 
tape and makes it again available for use. 
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2. Determine the sequential number of the file which was 
interrupted and use the /M construction to enter a 

replacement file (either a new file or a dummy file) • 
Assuming the bad file is the 4th file on the tape, use a 
command line of this construction: 

*devO:file.new=file.dum/M:-4 

A logical end-of-tape now exists on the tape, making it 
available for use. 

Since magtapes and cassettes are not random access devices, each unit 
can have only one file accessed at a time. Avoid PIP command strings 
which specify the same unit number for both input and output, since a 
loss of information can occur. For example: 

*CT0:FI LEI.MAC= CT0:FIL £1.MAC 
?FIL NOT FND? 

* 

The result of this operation is to delete FILEl.MAC before the error 
message is printed, and the tape label structure may be destroyed. 

Recovery procedures for errors caused by bad tapes are described in 
RT-11 Software Support Manual . 
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4.2.2 Copy Operations 

A command line without a switch causes files to be copied onto the 
destination device in image mode (byte by byte). This operation is 
used to transfer memory image (save format) files and any files other 
them ASCII or formatted binary. For example: 

*flBC<XVZ Makes a copy of the file named XYZ on 

device DK and assigns the name ABC. 
(Both files exist on device DK following 
the operation). 

*SV:BACK. BIN=PR :/ I Copies a tape from the papertape reader 

to the system device in image mode and 
assigns it the name BACK.BIN. 

The /A switch is used to copy file(s) in ASCII mode as follows: 

*DT1 : Fl<CF2/fi Copies F2 from device DK onto device DTI 

in ASCII mode and assigns the name FI. 

Nulls and rubouts are ignored in an ASCII mode file transfer. CTRL Z 
(32 octal) is treated as logical end-of-file if encountered in the 
input file. 

The /B switch is used to tramsfer formatted binary files. The 
formatted binary copy switch should be used for .OBJ files produced by 
the assembler or FORTRAN and for .LDA files produced by the Linker. 
For example: 

*DK : FILE. OBJCPR:/B Transfers a formatted binary file from 

the papertape reader to device DK and 
assigns the name FILE.OBJ. 

When performing formatted binary transfers, PIP verifies checksums and 
prints the message ?CHK SUM? if a checksum error occurs. 

If neither /A nor /B is used in a copy operation that involves a paper 
tape device, the size of the output file in the operation depends upon 
the memory size of the system. The transfer mode defaults to image 
mode and PIP attempts to do a single read to fill its input buffer. 

When a read from the paper tape reader encounters end-of-tape, no count 
of words transferred can be returned? PIP assumes its input buffer is 
full and copies it to the output device. The output file size thus 
depends upon the input buffer size, which is determined by the memory 
size of the system. The output file will have several blocks of zeroes 
after the end of the paper tape image. If copying to the punch, large 
amounts of blank tape will be punched after the input tape image is 
output. The extra length is harmless, but can be avoided by use of /A 
or /B. Image mode files (for example, .SAV files) cannot reliably be 
transferred to or from paper tape. 

To combine more than one file into a single file, use the following 
format: 


*DK:ft ft < D T1:BB,CC,DD/I 

Transfers files BB, CC and DD to device 
DK as one file and assigns this file the 
name AA. 
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*DT3:MERGE S DT2:FILES,FILES/R 

Merges ASCII files FILE2 and FILE3 on 
DT2 into one ASCII file named MERGE on 
device DT3• 

Errors which occur during the copy operation (such as a parity error) 
cause PIP to output an error message and return for another command 
string. 

The /G switch is used to copy files but ignore all input errors. For 
example: 

* ft B C < D T1 : TOP / G Copies file TOP in image mode from 

device DTI to device DK and assigns the 
name ABC, Any errors during the copy 
operation are ignored. 
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*DT2:CGMBCDTl:FI,F2/A/G 

Copies files FI and F2 in ASCII mode 
from device DTI to device DT2 as one 
file with the name COMB. Ignores input 
errors. 

The wild card construction may be used for input file specifications 
during copy operations. Be sure to use the /Y switch if system files 
(.SYS) are to be copied. For example: 

#DT1 ♦ PROG1<* ♦ MAC Copies, in image mode, all files with a 

.MAC extension from device DK to device 
DTI and combines them under the name 
PR0G1• 

****=DT3:**#/G/Y/X Copies to device DK, in image mode, all 

files (including .SYS files) from device 
DT3; ignores any input errors. 

If only files with the current date are to be copied (using the wild 
card construction), the /C switch must also be used in the command 
line. For example: 


*DT2:NN3=ITEM1. */C, ITEM2/H 

Copies, in ASCII mode, all files having 
the filename ITEM1 and the current date, 
(the date entered using the monitor DATE 
command) and copies ITEM2 (regardless of 
its date) from device DK to device DT2 
and combines them under the name NN3. 

*DT3:*. *=*. */C/X Copies all files with the current date 

from DK to DT3. Note that commands of 
this nature are an efficient way to 
backup all new files after a session at 
the computer. 

The /Q switch is used in conjunction with another PIP operation and 
the wild card construction to list all files and allow the user the 
opportunity to confirm individually which of these files should be 
processed during the wild card expansion. Typing a "Y" causes the 
named file to be processed; typing anything else excludes the file. 
For example: 


**♦GBJCDT1:*♦GBJ/Q/X 
FIRST ♦OBJ?Y 
GETR ♦OBJ? 

BORD ♦OBJ? 

CARJ ♦OBJ?Y 


Copies the files FIRST.OBJ and 
CARJ.OBJ to the disk in 
image mode from DECtape 1 
and ignores the others. 


The file allocation scheme for RT-11 normally allows half the entire 
largest available space or the second largest space, or a maximum size 

(a constant which may be patched in the RT-11 monitor; see the RT-11 
System Generation Manual) , whichever is largest, for a new file. The 
user can, using the In] construction explained in Chapter 2, force 
RT-11 to allow the entire largest possible space by setting n=177777. 
If n is set equal to any other value (other than 0 which is default 
and gives the normal allocation described first above), that size will 
be allocated for the file. 
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Therefore, assume that the directory for a given device shows a free 
area of 200 blocks and that PIP returns an ?OUT ER? message when a 
transfer is attempted to that device with a file which is longer than 
100 blocks but less than 200 blocks. Transfers in this situation can 
be accomplished in either of two ways: 

1. Use the [n] construction on the output file to specify the 
desired length (refer to Chapter 2, Section 2.5 for an 
explanation of the [n] construction)• 

2. Use the /X switch during the transfer to force PIP to 
allocate the correct number of blocks for the output file. 
This procedure will operate correctly if the input device is 
DECtape or disk. 

For example, assume that file A is 150 blocks long and that a 
directory listing shows that there is a 200 block <unused> space on 
DTI: 

. R PIP 

*DT1:fi = fl 

? 0UT ER? File longer than 100 blocks. 

* DTI:fi[150 ] = ft 

or Either command causes a correct 

*DT1:R = R / X transfer. 


4.2.3 Multiple Copy Operations 

The /X switch allows the transfer of several files at a time onto the 
destination device as individual files. The /A, /G, /C # /Q, /B and /Y 
switches can be used with /X. If /X is not indicated, all output files 
but the first will be ignored. 

Examples: 


* FIL E1 y FIL E 2 y F11... E 3 < D T 1 S FIL E A y F1L E B y FIL E C / X 


Copies, in image mode, FILEA, FILEB and 
FILEC from device DTI to device DK as 
separate files called FILE1, FILE2 and 
FILE3, respectively. 


*DT2 : FI. * = F2. */X 
?N0 SVS FICTION? 

* 


Copies, in image mode, all files named 
F2 (except files with .SYS or .BAD 
extensions) from device DK to device 
DT2. Each file is assigned the filename 
FI but retains its original extension. 


#DT1 i * * *-DT2 * *♦ M/X Copies, in image mode, all files on 
?N0 SYS ACTION? device DT2 to device DTI (except files 

with .SYS or .BAD extensions); the files 
are copied separately and retain the 
same names and extensions. 


*DT1:FILEI,F I LE2CF I LER. */R/G/X 

This command line assumes there are two 
files with the filename FILEA (and any 
extension excluding .SYS or .BAD 
extensions) and copies these files in 
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ASCII mode to device DTI. The files are 
transferred in the order they are found 
in the directory; the first file found 
is copied and assigned the name FILE1, 
and the second is assigned FILE2. If 
there is a third, it is ignored and a 
fourth causes an ?OUT FIL? error. 

*DT0 : *. SVS = *. SVS/X/V 

Copies all system files from device DK 
to device DTO• 

File transfers performed via normal operations place the new file in 
the largest available area on the disk. The /X switch, however, 
places the copied files in the first free place large enough to 
accommodate it. Therefore, the /X switch should be used whenever 
possible (i.e., when no concatenation is desired) as an aid to 
reducing disk fragmentation. 

*fi=B 

and 

*ft=BVX 

perform the same operation; however, using the second construction 
whenever possible increases the system disk-usage efficiency. 

For example, assume the directory of DTI iss 

9-MRV-74 


MONITR. 5VS 

2 2 

5 - M ft V - 7 4 

< UNUSED > 

c. 


PR . SVS 

2 

S-MftV-74 

< UNUSED > 

528 



2 FILES, 24 BLOCKS 
528 FREE BLOCKS 

To copy the file PP.SYS (2 blocks long) from DK to DTI, the command: 

*DT1 : PR. SVS = PP. SVS/V 

can be entered, and the new directory is: 

9-MRV-74 


MONITR. SVS 

22 

5 - M ft V - 7 4 

< UNUSED > 

o 

c. 


PR 

. SVS 

2 

5 - M ft V - 7 4 

PP 

. SVS 

2 

9 - M ft V - 7 4 

< UNUSED > 

526 



2 FILES, 26 BLOCKS 
528 FREE BLOCKS 

If the command: 

*DT1 : PP. SVS = PP. SVS/V/X 

had been entered, the new directory would appear: 
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9-MftV-74 


MONITR. 5VS 

22 

5-MftV-74 

PR . SVS 

2 

9-MRV-74 

PR . SVS 

2 

5-MRV-74 

< UNUSED > 

528 


3 FILES, 2G 

BLOCK 

c, 


528 FREE BLOCKS 

4.2.4 The Extend and Delete Operations 

The /T switch is used to increase the number of blocks allocated for 
the specified file. The file associated with the /T switch must be 
followed by a numeric argument of the form [n] where n is a decimal 
number indicating the number of blocks to be allocated to the file at 
the completion of the extend operation. 

The format of the /T switch iss 

dev:filnam.ext[n]=/T 

A file can be extended in this manner only if it is followed by an 
unused area of sufficient size (on whichever device it is located) to 
accommodate the additional length of the extended file. It may be 
necessary to create this space by moving other files on the device 
using the /X switch. 

Specifying the /T switch in conjunction with a file that does not 
currently exist creates a file of the designated length. 

Error messages are printed if the /T command makes the specified file 
smaller (?EXT NEG?) or if there is insufficient space following the 
file (?ROOM?). 

Examples: 


* ft B C [ 200 ] = /T Assigns 200 blocks to file ABC on device 

DK. 

*DT1: X’VZC 100 K/T Assigns 100 blocks to the file named XYZ 

on device DTI. 

The /D switch is used to delete one or more files from the specified 
device. The wild card character (*) can be used in conjunction with 
this command. 

Only six files can be specified in a delete operation if each file to 
be deleted is individually named (i.e., if the wild card character is 
not used). 

A cassette or magtape may be initialized by indicating the /D switch 
and omitting any filenames. For example: 

*MT :/0 
*CT :/D 

Both devices are zeroed. This is not the case with the other RT-11 
devices, where omission of a filename causes no action to occur. 
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When a file is deleted on block-replaceable devices, the information 
is not destroyed. The file name is merely removed from the directory. 
If a file has been deleted but not overwritten, it can be recovered 
with the /T switch by specifying a command of the forms 

filena.ext[n]=/T 

where filena.ext is the name desired and n is the length of the 
deleted file. For examples 

*DT1 :/E 
4-JUN-74 


ft 

. MftC 

18 

2-JUN-74 

B 

. M ft C 

17 

2-JUN-74 

C 

. MftC 

19 

2-J UN- 74 

< 

UNUSED > 

510 


3 

FILES/ 54 

BLOCKS 


510 FREE BLOCKS 


*DT1:B. MAC 

/D 


♦DTI:/E 



4-JUN-74 



ft . MftC 

18 

2-JUN-74 

< UNUSED > 

17 


C . MftC 

19 

2-JUN-74 

< UNUSED > 

510 



2 FILES/ 27 BLOCKS 
527 FREE BLOCKS 

File B.MAC could now be recovered bys 
*DT1:B. MftCC17 1-/T 

The /T switch looks for the first unused area large enough to 
accommodate the requested file length. If the file to be recovered is 
in the first area large enough to accommodate the size specified, the 
preceding command is sufficient. If not, all larger unused spaces 
preceding the desired file must be given dummy names before the 
recovery can be made. 

For instance, assume the previous example with the exception that 
A.MAC has a 33 block unused file before it, so that the directory 
looks likes % 

*DT1:/E 
4-JUN-74 


< 

UNU5ED > 

23 


ft 

. MftC 

18 

2-JUN-74 

*■ 

UNUSED > 

17 


C 

. MftC 

19 

2-JUN-74 

< 

UNUSED > 

477 


2 

FILES, 27 

BLOCKS 


527 FREE BLOCKS 


A recovery of B.MAC would requires 

♦ DT1.DUMMVC22WT 
*DT1 : B. MftCC 17 3=/T 
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If the 33 block unused area was not named prior to B.MAC, the first 17 
blocks of the 33 block area would become B.MAC. Note that magtape and 
cassette files cannot be recovered once deleted. 

Examples: 


*FILE1. SftV /0 


Deletes FILE1.SAV from device DK. 


*DT1 : */t> Deletes all files from device DTI except 

those with a .SYS or .BAD extension. If 
there is a file with a .SYS or .BAD 
extension, the message ?N0 SYS ACTION? 
is printed to remind the user that these 
files have not been deleted. 

** MRC/D Deletes all files with a .MAC extension 

from device DK. 

*DT1:61,DT2:Rl, DT2:flfl/D 

Deletes the files specified from the 
associated devices. 


*RK1 i #.#/D/Y Deletes all files from device RK1. 


4.2.5 The Rename Operation 

The /R switch is used (in a manner similar to the multiple copy 
command described in Section 4.2.3) to rename a file given as input 
with the associated name given in the output specification. There 
must be an equal number of input and output files and they must reside 
on the same device, or an error message will be printed. The /Y 
switch must be used in conjunction with /R if .SYS files are to be 
renamed. 

The Rename command is particularly useful when a file on disk or 
DECtape contains bad blocks. By renaming the file with a .BAD 
extension, the file permanently resides in that area of the device so 
that no other attempts to use the bad area will occur. Once a file is 
given a .BAD extension it cannot be moved during a compress operation. 
.BAD files are not renamed in wild card operations unless /Y is used. 

Examples: 


*DT1:FI, X1<DT1 : F0, X8/R Renames FO to FI and XO to XI on 

device DTI. 

*FILE1. + CFILE2.*/R Renames all files on device DK with 

the name FILE2 (except files with 
.SYS or .BAD extension) to FILEl, 
retaining the original extensions. 

/R cannot be used with magtape or cassette. 

4.2.6 Directory List Operations 

The /L switch lists the directory of the specified device. The 
listing contains the current date, all files with their associated 
creation dates, total free blocks on the device if disk or DECtape, 
the number of files listed, and number of blocks used by the files 
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(sequence number for cassette). File lengths, number of blocks and 
number of files are indicated as decimal values. If no output device 
is specified, the directory is output to the terminal (TTs). 

Examples s 


* D T1: / L 
l-fiUG-74 


MONITR. 

5 VS 

32 

5-MAV-74 

F’P 

5 VS 

2 

9-MAV-74 

PR 

SVS 

2 

S-MftV-74 

F 2 

REL 

15 


MERGE 


o 

c. 


COMB 


2 


b FILES# 55 

BLOCKS 


509 FREE BLOCKS 


*DIRECT=DT 

3: /l 

**. MfiC/L 


l-RUG-74 


VTMflC . MAC 

7 22-JUL-74 

FILE2 . MAC 

1 

2 F I L E 5, 8 

BLOCKS 

3728 FREE 

BLOCKS 

♦ 



*CT 1 :/L 
10-SEP-74 
F'flTl . FOR 

0 10-SEP-74 

PftT2 

. FOR 

0 10-SEP-74 

IMUL 

. OBJ 

0 10-SEP-74 

SORT 

. FTN 

0 10-SEP-74 

4 FILES# © 

BLOCKS 


Outputs complete directory of 
device DTI to the terminal. 


Outputs complete directory of 
device DT3 to a file, DIRECT, 
on the device DK. 

Lists on the terminal a 
directory of files on device 
DK with the extension .MAC. 


Lists all files on cassette 
drive 1. For cassette only, 
the third column represents 
the sequence number. In 
this example, the first seg¬ 
ment of each file is on this 
cassette. (See Section 
4.2.1.) 


The /E switch lists the entire directory including the unused areas 
and their sizes in blocks (decimal); an empty space appears in 
cassette and magtape directories to designate a deleted file. 


Examples s 


*/e 

9-SEP-74 


BATCH ♦HLP 

2 

23-AUG-74 

CHESS ♦ SAU 

20 

23-AUG-74 

PAT1 ♦FOR 

10 

23-AUG-74 

IRAD50 ♦ MAC 

8 

23-AUG-74 


Outputs to the terminal a 
complete directory of the 
device DK including the size 
of unused areas. 
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< UNUSED > 

2 





TRIG ♦OBJ 

2 

6-SEP-74 




SIP ♦OBJ 

2 

6 -SEP-74 




BAG ♦OBJ 

2 

6-SEP-74 




< UNUSED > 

♦ 

20 





4 

LIBR1 4 OBJ 

137 

6-SEP-74 




DIRECT 

1 

9-SEP-74 




< UNUSED > 

230 





254 FILES 9 

4280 

BLOCKS 




498 FREE BLOCKS 





*LF‘ : =CT 1: /E 



Outputs to 

the line printer 

1l-SEP-7« 



a complete 

directory 

of 

A .MAC 

0 

11«SEP*74 

cassette 

drive 1. 

0's 

A , MAC 

0 

U«3Ep*74 

represent segment numbers. 


B .MAC 

0 

IUSERp74 





3 FILES, 0 BLOCKS 

The /F switch lists only filenames, omitting the file lengths and 
associated dates. 

Examples: 

*DT0 :/F 
TRACE . MAC 
CARGO . REL 
BMAP . OBJ 
ftA A 

*LP:=CT1 :/F 


A .MAC 

A f MAC 

B .MAC 

The /L, /E and /F commands have no effect on the files of the speci¬ 
fied device. If the /W switch is used in conjunction with the /L or 
/E switches, the absolute starting block of the file and extra words 
(in octal) will be included in the listing (for all but cassette and 
magtape). For example: 


*rki:/l/u 

10-SEP-74 


DSQRT * OBJ 

1 

10-SEP-74 

16 

0 

MAIN 4 OBJ 

1 

10-SEP-74 

17 

0 

BASICR 4 OBJ 

11 

10-SEP-74 

20 

0 

o rSO2 * OBJ 

3 

10-SEP-74 

33 

0 


The first three columns indicate the filename and extension , block 
length , and date. The fourth column shows the absolute starting block 
(in octal ), and the fifth column shows the contents of each extra word 
per directory entry (in octal). (This is allocated using the /Zsn 
switch; see Section 4.2.7.) 


Outputs a filename directory 
of the device DTO to the 
terminal. 


Outputs a filename directory 
of the device CT1 to the line 
printer. 


4-17 


January 1976 




Peripheral Interchange Program 


Using the /L, /E, or /F switch in conjunction with a device and 
filename causes the filename, and optionally the date and file length, 
to be output rather than a directory of the entire device. For 
example s 

*F1. SfiV/L 

causes: 

4-JUN-74 

FI . SftV 18 4 -JUN-74 

3710 FREE BLOCKS 
* 

to be output, providing the file exists on device DK. 

Directories are made up of segments which are two blocks long. Full 
directory listings with multiple segments contain blank lines as 
segment boundaries. 

4.2.7 The Directory Initialization Operation 

The /Z switch clears and initializes the directory of an RT-11 direc¬ 
tory-structured device and writes logical end-of-file to a cassette 
or magtape device. The /Z operation must always be the first opera¬ 
tion performed on a new (that is, previously unused) device. The 
form of the switch is: 

/Z:n 

where n is an optional octal number to increase the size of each direc¬ 
tory entry on a directory-structured device. If n is not specified, 
each entry is 7 words long (for filename and file length information) 
and 70 entries can be made in a directory segment. When extra words 
are allocated, the number of entries per directory segment decreases. The 
formula for determining the number of entries per directory segment is: 

507/((# of extra words)+7) 

For example, if the switch /Z:l is used, 63 entries can be made per 
segment. 

More information concerning the format of directory entries is supplied 
in Chapter 3 of the RT-11 Software Support Manual . 

When /Z is used, PIP responds as follows: 

device/Z ARE YOU SURE ? 

For example: 

*DT1:72 

DTI:72 ARE VOU SURE ? 

Answer Y and a carriage return to perform the initialization, 
answer beginning with a character other than Y is considered to be 

Example: 

*DT1 :/Z 

DTI: 72 ARE VOU SURE ?V<CR> 

* Zeroes the directory on device DTI 

allocates no extra words for 
directory. 


An 

no. 


and 

the 


January 1976 


4-18 





Peripheral Interchange Program 


The /N switch is used with /Z to specify the number of directory seg¬ 
ments for entries in the directory. The form of the switch is: 

/N:n 

where n is an octal number less than or equal to 37. Initially RT-11 
allocates four directory segments, each two blocks (512 words) long. 
Refer to Chapter 3 of the RT-11 Software Support Manual for more in- 
formation. 

Example: 


*RK1 1 /Z♦2/N 1 6 Zeroes the directory on device RKl, al¬ 

locates two extra words per directory 
entry and allocates six directory seg¬ 
ments . 

4.2.8 The Compress Operation 

The /S switch is used to compress the directory and files on the speci¬ 
fied device, condensing all the free (unused) blocks into one area. 
Input errors are reported on the console terminal unless the /G switch 
is used; output errors are always reported. In either case, the com¬ 
press continues. /S can also be used to copy DECtapes and disks. 

When DT, DP, or RK devices are copied, /S serves to both initialize 
the volume and to copy directory and files. When DX disks are copied, 
however, the output diskette must first be initialized using /Z to 
write the appropriate volume identification. (It is important to 
note that the /S switch destroys any previous directory on the output 
device. The new directory on the output device has the same number 
of segments as the directory on the input device.) /S does not copy 
the bootstrap onto the volume. 

To increase the number of directory blocks in a two-volume compress 
(that is, from one volume to another rather than from one volume to 
itself), use the /N:n switch in conjunction with the /S switch (any 
attempts to decrease the directory size are ignored)• 

/S does not move files with the .BAD extension. This feature provides 
protection against reusing bad blocks which may occur on a disk. 
Files containing bad blocks can be renamed with the .BAD extension and 
are then left in place when a /S is executed. 

If a compress operation is performed on the system device, the 
message: 


7REB00T? 

is printed to indicate that it may be necessary to reboot the system. 
If .SYS files were not moved during the compress operation, it is not 
necessary to reboot the system. 


NOTE 

Rebooting the system in response to the 
?REBOOT? warning message should ONLY be 
done AFTER the operation which generated 
the message is complete. ?REBOOT? does 
not signify that the system should be 
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rebooted immediately; the user should 
wait for the signifying that PIP is 
ready for another command before 
rebooting. 


If the command attempts to compress a large device to a smaller one, 
an error results and the directory of the smaller device is zeroed. 
If a device is being compressed in place, input and output errors are 
reported on the terminal and the operation continues to completion. 

Examples: 


* 5 V :/ 5 Compresses the files on the system 

"‘REBOOT? device SYs 

*DT1: FKDT2 :/S Transfers and compresses the files from 

device DT2 to device DTI, Device DT2 is 
not changed. The filename A is a dummy 
specification required by the Command 
String Interpreter, 

/S cannot be used when a foreground job is present; a ?FG PRESENT? 
error message results if this is attempted. 


4.2.9 The Bootstrap Copy Operation 

The bootstrap copy switch (/U) copies the bootstrap portion of the 
specified file into absolute blocks 0 and 2 of the specified device. 

Examples: 

*DK:ft<DK:M0NITR. SVS/U 

Writes the bootstrap file MONITR,SYS in 
blocks 0 and 2 of the device DK. A is a 
dummy filename. 

* n T: M 0 NIT R ♦ S Y S / X / Y * R K t D T M N S J * S Y S 
*DTtA=RK♦DTMNSJ♦SYS/U 

Writes the Single-Job DECtape Monitor 
to device DTO and then writes the boot¬ 
strap into blocks 0 and 2 (the bootstrap 
is written from disk rather than DECtape 
because disk is faster). 


4.2.10 The Boot Operation 

The boot switch reboots the system, reinitializing monitor tables and 
returning the system to the monitor level. The boot switch performs 
the same operation as a hardware bootstrap. 

Example: 

*DK:/0 Reboots the device DK. 
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If a boot switch is specified on an illegal device, the message: 
?BAD BOOT? 

is printed. Legal devices are DTO, RK0-RK7, RF, SY, DK, DP0-DP7 
DX0-DX1, and DS0-DS7. Note that /O is illegal if a foreground job 
is present; the ?FG PRESENT? error message results. The user must 
abort the foreground job and unload it before using /0. 


4.2.11 The Version Switch 

The Version switch (/V) outputs a version number message (representing 
the version of PIP in use) to the terminal using the form: 

PIP V02-XX 

The rest of the command line, if any, is ignored. 


4.2.12 Bad Block Scan (/K) 

The bad block switch (/K) scans the specified device and types the 
absolute block numbers of those blocks on the device which return 
hardware errors. The block numbers typed are octal; the first block 
on a device is 0(8). Note that if no errors occur, nothing will be 
output. A complete scan of a disk pack takes several minutes. 

Example: 

KRK2S/K Scan disk drive 2 for bad blocks. 

BLOCK 140 IS BAD 


♦RK./K Scan drive 0. No blocks are bad. 

* 


4.2.12.1 Recovery from Bad Blocks 

As a disk ages, the recording surface wears. Eventually unrecoverable 
I/O errors occur during attempts to read or write a bad disk block. 
PIP protects against usage of bad disk areas by ignoring files with a 
.BAD extension (unless the /Y switch is used). Once a bad block is 
uncovered in an I/O operation, it can be located using the /K switch 
and a .BAD file can be created which encompasses the bad block. 

When a hardware I/O error is detected, the recovery procedure is as 
follows: 

1. Use the PIP /K switch to scan the device and print on the 
terminal the absolute block numbers (in octal) of the bad 
blocks. For example: 

R PIP 
*RK1 :/K 

BLOCK ??23 IS BAD 
* 
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2 . Obtain an extended directory with the /W switch, showing the 
starting block numbers of all the files on the disk. 

3. If a bad block occurs in a file with valuable information, 
copy the file to another file using the /G switch. In most 
cases, only 1 bit (character) of the file is affected. 

4. If the file is small, it can then be renamed with a .BAD 
extension to prevent further use of that disk area. 


5. If the file is large or the bad block occurs in an empty 

area, a 1-block .BAD file can be created using the /T switch 

as follows: 

a. Delete the bad file (if any). 

b. If the bad block is at block n of the free area, create a 
file of length n-1 with the /T switch. Remember that 
there must be no spaces larger than n-1 blocks before the 
desired one (refer to Section 4.2.4). Also note that the 
block numbers printed in the /K and /W operations. are 
octal, while the argument to the /T operation is decimal. 

c. Create a 1-block .BAD file with the /T switch to cover 
the bad block. 

d. Delete any temporary files created during the operation. 

For example, assume the extended directory is: 


NEmSKC.bat 

8 

11-5EP-74 

RTTEMP.BAT 

27 

1l-SEP-74 

PIP .MAC 

150 

12-SEP-74 

« UNUSED > 

154 


VERIFY.SAV 

3 


« UNUSED > 

300 


PIP .08J 

15 

12-SEP-74 

MKPIP .CTL 

l 

12-$EP*74 

MKV2RK.CTL 

4 

12-SEP-74 

VTLIB .OBJ 

10 

12-SEP*74 

« UNUSED > 

150 


A 

4 

12-SEP-74 

PIP .LST 

300 

3-SEP-74 


6203 

6213 

6246 

6726 

7405 

7424 

7425 
7431 

767 1 

7675 Block 7723 (octal) of 
PIP.LST is bad. 


and a bad block is detected at block 7723 (octal) of the file PIP.LST. 
To recover, make a copy, ignoring the error, and delete the bad file: 


*RK1:PIPfl.LST=RK1:PIP.LST/G 
*RK1:PIP. LST/D 

The directory now reads: 


NEWSRC.BAT 8 ll-SEP-74 
RTTEMP.BAT 27 ll-SEP-74 
PIP .MAC 150 12-SEP-74 


6203 

6213 

6246 
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< UNUSED > 

154 

VERIFY,SAV 

3 

PIPA ,L3T 

300 

PIP .OBJ 

15 

MKPIP .CTL 

1 

MKV2RK.CTL 

4 

VTIIB .OBJ 

10 

< UNUSED > 

150 

A 

4 


18-SEP-74 

6726 

6731 

12-SEP-74 

7405 

12-SEP-74 

7424 

12-SEP-74 

7425 

12-SEP-74 

7431 

12-SEP-74 

7671 




An unused area following A contains block 7723 (octal), which 
is bad. Continuing in PIPs 

*RK1: TEMP. 002C 154 ]=/T 
*RK1: TEMP. 00I<[ 150 1=/T 
*RK1:TEMP. 004C223=/T 

This fills the unused areas with temporary files. Specifying 
TEMP.004 with a length of 22 blocks makes the file just long 
enough to precede the bad block (i.e., 7675 (octal) and 22 
(decimal) equal 7723, which would be the starting block 
number of the next file created). The directory now contains: 


NEWSRC.BAT 

8 

1 l-SEP-74 

rttemp.bat 

27 

ll-SEP-74 

PIP .MAC 

150 

12-SEP-74 

TEMP ,002 

154 

18-SEP-74 

VERIFY.SAV 

3 


PIPA .LST 

300 

18-SEP-74 

PIP .OBJ 

15 

12-SEP-74 

MKPIP .CTL 

1 

12-SEP-74 

MKV2RK.CTL 

4 

12-SEP-74 

VTLIB .OBJ 

10 

12-SEP-74 

TEMP ,003 

150 

18-SEP-74 

A 

4 

12-SEP-74 

TEMP .004 

• 

22 

18-SEP-74 

• 

Continuing with 

PIP: 


* R K1 FILE. 

BRDC i ] = .•••'V/T 

The directory now contains: 

• 

• 

NEWSRC.BAT 

8 

ll-SEP-74 

RTTEMp.BAT 

27 

1l-SEP-74 

PIP .MAC 

150 

12-SEP-74 

TEMP ,002 

154 

18-SEP-74 

VERIFY.SAV 

3 


PIPA .LST 

300 

18-SEP-74 

PIP .OBJ 

15 

12-SEP-74 

MKPIP ,CTL 

1 

12-SEP-74 

MKV2RK.CTL 

4 

12-SEP-74 

VTLIB .OBJ 

10 

12-SEP-74 

TEMP .003 

150 

18-SEP-74 

A 

4 

12-SEP-74 


6203 

6213 

6246 

6474 

6726 

6731 

7405 

7424 

7425 
7431 
7443 
7671 
7675 


Create a bad file. 


6203 

6213 

6246 

6474 

6726 

6731 

7405 

7424 

7425 
7431 
7443 
7671 
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TEMP ,00a 22 18-SEP-74 7675 
FILE .BAD 1 18-SEP-74 7723 

’ Bad block is here. 

Next delete all temporary files and rename PIPA.LST to 
PIP.LST. The final directory now contains: 


NEWSRC.BAT 

8 

ll-SEP-74 

6203 

pttemp.bat 

27 

U-SEP-74 

6213 

PIP .MAC 

150 

12-SEP-74 

6246 

< UNUSED > 

154 



VERIFY.SAV 

3 


6726 

PIP ,LST 

300 

18-SEP-74 

6731 

PIP .OBJ 

15 

12-SEP-74 

7405 

MKPIP ,CTL 

1 

12-SEP-74 

7424 

MKV2RK.CTL 

4 

12-SEP-74 

7425 

VTLIB .OBJ 

10 

12-SEP-74 

7431 

< UNUSED > 

150 



A 

4 

12-SEP-74 

7671 

< UNUSED > 

22 



FILE .BAD 

1 

18-SEP-74 

7723 


Disks with many bad blocks can often be reused by 
reformatting them. First copy all desired files, since 
reformatting destroys all information contained on a volume. 

4.3 PIP ERROR MESSAGES 

The following error messages are output on the terminal when PIP is 
used incorrectly: 


Errors 

Meaning 

?BAD BOOT? 

A boot switch was specified on an illegal 
device. 

?BOOT COPY? 

An error occurred during an attempt to write 
bootstrap with /U switch. 

?CHK SUM? 

A checksum error occurred in a formatted 
binary transfer. 

?COR OVR? 

Memory overflow—too many devices and/or file 
specifications (usually *.* operations) and 
no room for buffers. 

?DEV FUL? 

No room on device for file. 

?ER RD DIR? 

Unrecoverable error reading directory. Check 
volume for off-line or write-locked condition 
and try the operation again. 

?ER WR DIR? 

Unrecoverable error writing directory. Try 

again. 

?EXT NEG? 

A /T command attempted to make file smaller. 

?FG PRESENT? 

An attempt was made to use /0 or /S while a 
foreground job was still in memory. Unload 
it if it is no longer desired. 

?FIL NOT FND? 

File not found during a delete, copy, or re¬ 
name operation, or no input files with the 
expected name or extension were found during 
a *.* expansion. 
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?ILL CMD? 

The command specified was not syntactically 
correct; a device name is missing which 
should be specified, a switch argument is too 
large, a filename is specified where one is 
inappropriate, or a nonfile-structured device 
is specified for a file-structured operation. 

?ILL DEV? 

Illegal or nonexistent device. 

PILL DIR? 

The device did not contain a properly ini¬ 
tialized directory structure (EOT file on 
magtape and cassette; empty file directory 
on other devices). Use /Z. 

PILL REN? 

Illegal rename operation. Usually caused by 
different device names on the input and out¬ 
put sides of the command string. 

PILL SWT? 

Illegal switch or switch combination. 

PIN ER? 

Unrecoverable error reading file. Try again 
(this error is ignored during /G operation). 

POUT ER? 

Unrecoverable error writing file. Perhaps a 
hardware or checksum error; try recopying 
file. Also may be caused by an attempt to 
compress a larger device to a smaller one or 
by not enough room when creating a file. The 
system takes the largest space available and 
divides it in half before attempting to in¬ 
sert the file. Try the [n] construction or 
/X switch. 

POUT FIL? 

Illegal output file specification or missing 
output file. 

PROOM? 

Insufficient space following file specified 
with a /T switch. 


The following warning messages are output by PIP: 
CTn: PUSH REWIND OR MOUNT NEW VOLUME 


?N0 .SYS/.BAD 
ACTION? 

A new cassette must be mounted on drive n to 
allow continuation of an I/O operation* The 
operation is continued automatically as soon 
as the new cassette is mounted. 

The /Y switch was not included with a command 
specified on a .SYS or .BAD file. The com¬ 
mand is executed for all but the .SYS and 
.BAD files. A *.* transfer is most likely 
to cause this message. 

?REBOOT? 

.SYS files have been transferred, renamed, 
compressed or deleted from the system device. 
It may be necessary to reboot the system. 

NOTE 

The message is typed immediately 
after execution of the relevant 
command has begun, but the actual 
reboot operation must not be per¬ 
formed until PIP returns with the 
prompting asterisk for the next 
command. If the system is halted 
and rebooted before the prompting 
asterisk returns, disk information 
may be lost. 

4-25 January 1976 


January 1976 











Peripheral Interchange Program 


If any of the .SYS files in use by the 
current system (MONITR.SYS and handler files) 
have been physically moved on the system 
device, it is necessary to reboot the system 
immediately. If not, this message can be 
ignored. If the cause of the message was a 
/S operation, the system need be rebooted 
only if there was an empty space before any 
of the .SYS files or if the /N:n switch was 
used to increase the number of directory 
segments. The need to reboot can be 
permanently avoided by placing all .SYS files 
at the beginning of the system device, then 
avoiding their involvements in PIP operations 
by not using the /Y switch. 

dev:/Z ARE YOU SURE? 

Confirmation must be given by the user before 
a device can be zeroed. 
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CHAPTER 5 
MACRO ASSEMBLER 


MACRO is a 2-pass macro assembler requiring an RT-11 system 
configuration (or background partition) of 12K or more. Macros are 
instructions in a source or command language which are equivalent to a 
specified sequence of machine instructions or commands. Users with 
minimum memory configurations must use ASEMBL and EXPAND and should 
read this chapter and Chapters 10 and 11 before assembling any 
programs. (The macro features not supported by ASEMBL are indicated 
in this chapter; many of the features not available in ASEMBL are 
supported by EXPAND.) 

Some notable features of MACRO ares 

1. Program control of assembly functions 

2. Device and file name specifications for input and output 
files 

3. Error listing on command output device 

4. Alphabetized, formatted symbol table listing 

5. Relocatable object modules 

6. Global symbols declaration for linking among object modules 

7. Conditional assembly directives 

8. Program sectioning directives 

9. User defined macros 

10. Comprehensive set of system macros 

11. Extensive listing control, including cross reference listing 
Operating instructions for the MACRO asserobler appear in Section 5.7. 
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5.1 SOURCE PROGRAM FORMAT 

A source program is composed of a sequence of source lines? each 
source line contains a single assembly language statement followed by 
a statement terminator. A terminator may be either a. line feed 
character (which increments the line count by 1) or a form feed 
character (which resets the line count and increments the page 
count by 1). 


NOTE 

EDIT automatically appends a line feed 
to every carriage return encountered in 
a source program. For listing format, 
MACRO automatically inserts a carriage 
return before any line feed or form feed 
not already preceded by one. 


An assembly language line can contain up to 132(decimal) characters 
(exclusive of the statement terminator). Beyond this limit, excess 
characters are ignored and generate an error flag. 


5.1.1 Statement Format 

A statement can contain up to four fields which are identified by 
order of appearance and by specified terminating characters. The 
general format of a MACRO assembly language statement is: 

label: operator operand(s) ;comments 

The label and comment fields are optional. The operator and operand 
fields are interdependent; either may be omitted depending upon the 
contents of the other. 

The assembler interprets and processes these statements one by one, 
generating one or more binary instructions or data words or performing 
an assembly process. A statement contains one of these fields and may 
contain all four types. Blank lines are legal. 

Some statements have one operand, for example: 

CL& R0 

while others have two: 

MOV #344,R2 

An assembly language statement must be complete on one source lin< . 
No continuation lines are allowed. (If a continuation is attempted 
with a line feed, the assembler interprets this as the statement 
terminator.) 

MACRO source statements may be formatted with EDIT so that use of the 
TAB character causes the statement fields to be aligned. For example: 
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Label 

Field 


Operator 

Field 


Operand 

Field 


CHECK: 

bit 


BEQ 


MOV 

EVEN: 

RTS 


#1,R0 

EVEN 

#-l,ODDFLG 

PC 


Comment 

Field 


;IS NUMBER ODD? 
;NO, IT'S EVEN 
;ELSE SET FLAG 
;RETURN 


5.1.1.1 
unique 


Label Field 
within the 


SS^fS2sv^ 1 Si 9 2S b g. o? 

SS-^SSPii currently iffi-- S= 

a program. If^Jsent^aHlabfl^lJaJs 09 t0 9 specific location within 

S St » i terminated b * a col™? ?or in 3 state ment aid 
is absolute 100(octal), the statement: Pl ' lf the current location 


ABCDi 


MQV 


A»B 


assigns the value 100 (octall f n a. Ko t t , 

location references location 100 (^tal) Subsequent reference 

location counter was declared ' . ta , ' • 1° this example if th*. 

final value of ABCD would be 100 (o SJ?? 1 *, Within the secSon, Se 
when it relocates the code, called thi PlU ? 3 value assigned by LINK 
fins! value of abcd woild tSrefSi n”\ 0ca * ion constant. * ?The 
Th ls as discussed later in this chaptS ,"f i^cS^r”" 1 Unk - ti ’“- 

Se t eaSh° n iaJ£ el „Uhin PP ?K “fSlS * 3in9 ^ Ubel field - in chich 
example, if the current locafinn ls assi 9 ne d the same value p nr 

labels in the statlS: C ° Unter is 100 (octal) , th? muitip?e 


CK^tXf maski 


A | 8 


the value 100 (SStai?” 6 labels ~ ABC / ERREX, and MASK—to be equated to 


A symbol used as 
An attempt to 
assembly listing. 


a label 
redefine 


may not be redefined 
a label results 


within the user program, 
m an error flag in the 


in 1 *n*statement°and^may ‘aJ&S??" ^ *U« the iabul £ield 

or an assembler directive. The opemor^ 1 V 3 " instruction mnemonic, 
or more labels and may be fol?™!^ 3y be P rec eded by zero, one 
°“"t- Leading ,„ d Sd^a^S?*’ ’ 

Whsn the oueratoy* 4 Q 

appropriate code to expand^h* 0911 ' the ass embler inserts the 
instruction mnemonic, it specifies the°instr W !?® n the °P erat °r is an 

operator^is an^SMeSi^ IlSTfiS S 

•ctxon to b, perfumed durSg C as^*iJ. 9Pe ° Xfles * Certal " *»»<*£.« 
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An operator is legally 
non-alphanumeric character 


terminated by a space, 
(symbol component). 


tab, or any 


Consider the following examples: 


MQV A,B 
MOV A A, B 


(space terminates the operator MOV) 
U terminates the operator MOV) 


SSed S feed or 

form feed character. 

A blank operator field is interpreted as a .WORD assembler directxve 
(See Section 5 . 5.3.2). 


. Ac d-v.r.i- oart of a statement which 
5 . 1.1.3 Operand Field - An ° per ^ erands ma y P be expressions, numbers, 
is manipulated by the operato . P ^ fche contex t of the operation), 
or symbolic or macro argument ( * statement, each is separated 

When multiple operands appear witn:Characters: comma, tab, space, 

from the next by one of the f 9 one or more operands (see Section 

or paired angle brackets . nr»<*rands are not legal (with 

5.2.1.1). Multiple delimiters separag combination of spaces and/or 
the exception of . s P*f* An Operand may be preceded by an 

operator^ 0 a 6 label “ Mother operaad and followed by a comment. 

The operand fleld is teminated^y^^aemloolo^ “^n^followed^by 

comment, or « 

statement. For example: 


LABEL: MOV A,B jCOMMENT 


The space between MOV and A terminates the A^andl^a 

semicolon^erminates thS o^nd Sid and begins the cogent field. 


sr^r£ IFr -F 

Bpecial^charactera *££ £S£S^. «• 
when appearing in the comment field. 

The eoa-nt field may be preeeded^y^ne.^ny. 

character 1 "and £?5i«K abatement terminator. 


is optional and may 
rubout, carriage return, 
other characters, even 
ignored by the assembler 


none or all of the 
begin with the semicolon 
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Comments do not affect assembly processing or program execution, but 
are useful in source listings for later analysis, debugging, or 
documentation purposes. 


5.1.2 Format Control 

Horizontal or line formatting of the source program is controlled by 
the space and tab characters. These characters have no effect on the 
assembly process unless they are embedded within a symbol, number, or 
ASCII text; or unless they are used as the operator field terminator. 
Thus, these characters can be used to provide an orderly source 
program. A statement can be written: 

IABEUM0V(3P)* # TAGfPOP VALUE OFF STACK 

or, using formatting characters, it can be written: 

LABfcll MOV (SP)*,TAG I POP VALUE OFF STACK 

which is easier to read in the context of a source program listing. 

Vertical formatting, i.e., page size, is controlled by the form feed 
character. A page of n lines is created by inserting a form feed 
(CTRL FORM) after the nth line. (See also Section 5.5.1.6 for a 
description of page formatting with respect to macros and Section 

5.5.1.2 for a description of assembly listing output.) 


5.2 SYMBOLS AND EXPRESSIONS 

This section describes the various components of legal MACRO 
expressions: the assembler character set, symbol construction, 
numbers, operators, terms and expressions. 


5.2.1 Character Set 

The following characters are legal in MACRO source programs: 

1. The letters A through Z. Both upper- and lower-case letters 
are acceptable, although, upon input, lower-case letters are 
converted to upper-case letters. Lower-case letters can only 
be output by sending their ASCII values to the output device. 
This conversion is not true for .ASCII, .ASCIZ, 1 (single 
quote) or " (double quote) statements if •ENABL LC is in 
effect. 

2. The digits 0 through 9. 

3. The characters . (period or dot) and $ (dollar sign) which 
are reserved for use in system program symbols (with the 
exception of local symbols; see Section 5.2.5). 

4. The following special characters: 
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Character Designation 


carriage return 
line feed 
form feed 
vertical tab 


Function 

formatting character 
source statement terminators 


% 

tab 

space 

# 

@ 

( 

) 


< 

> 

+ 


* 

/ 

& 

! 

n 

« 

t 

\ 


colon 

equal sign 
percent sign 


number sign 
at sign 

left parenthesis 
right parenthesis 
comma 
semicolon 

left angle bracket 

right angle bracket 

plus sign 

minus sign 

asterisk 

slash 
ampersand 
exclamation 
double quote 
single quote 
uparrow 

backslash 


label terminator 

direct assignment indicator 

register term indicator 

item or field terminator 

item or field terminator 

immediate expression indicator 

deferred addressing indicator 

initial register indicator 

terminal register indicator 

operand field separator 

comment field indicator 

initial argument or expression 

indicator 

terminal argument or expression 
indicator 

arithmetic addition operator or 
auto increment indicator 
arithmetic subtraction operator 
or auto decrement indicator 
arithmetic multiplication 

operator 

arithmetic division operator 
logical AND operator 
logical inclusive OR operator 
double ASCII character indicator 
single ASCII character indicator 
universal unary operator , 

argument indicator 
macro numeric argument indicator 
(not available in ASEMBL) 


5.2.1.1 Separating and Delimiting Characters - Reference is made in 
the remainder of the chapter to legal separating characters and macro 
argument delimiters. These terms are defined in Table 5-1 and 
following. 


Table 5-1 

Legal Separating Characters 


Character 

Definition 

Usage 

space 

one or more spaces 

A space is a legal separator 

and/or tabs 

only for argument operands. 
Spaces within expressions are 
ignored. 

9 

comma 

A comma is a legal separator 
for both expressions and 
argument operands. 

<...> 

paired angle brackets 

Paired angle brackets are used 
to enclose an argument, 


(Continued on next page) 
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Table 5-1 (cont.) 

Legal Separating Characters 


Character 

Definition 

Usage 

t\• • 

Up arrow construction 
where the up arrow 
character is followed 
by an argument 
bracketed by any paired 
printing characters. 

particularly when that 
argument contains separating 
characters. Paired angle 
brackets may be used anywhere 
in a program to enclose an 
expression for treatment as a 
term. (The angle bracket 
construction should be used 
when the argument contains 
unary operators.) 

This construction is 
equivalent in function to the 
paired angle brackets and 
is generally used only where 
the argument contains angle 
brackets. 


Macro arguments may appear in several forms to allow for special 
cases. The rules to observe when separating arguments are: 

1. If an argument string contains only non-separating characters 
(those not defined in Table 5-1) and no spaces, then it may 
appear in the argument list separated, if necessary, from the 
other arguments by commas. 

2. If an argument string contains separating characters or 

spaces, but does not contain the characters < or > (left or 
right angle brackets), then the argument may appear enclosed 
in paired angle brackets (e.g., <argument string>). The 
paired angle brackets are removed before the argument string 
is used. Successive pairs of angle brackets may be used to 
enclose an argument; only the outermost pair is removed. 

3. If an argument string contains separating characters or 

spaces (possibly including the left or right angle bracket 
characters), then it may appear in the following form: 
t\argument string\ where the backslashes may be replaced by 
any character not appearing in the argument string. The 
uparrow and backslashes (or other character) are removed 
before the argument string is substituted into the text. 

Note that regardless of the method used to specify an argument, it 
must be separated from any other arguments by commas. 


5.2.1.2 Illegal Characters - A character can be illegal in one of 
two ways: 

1. A character which is not recognized as an element of the 
MACRO character set is always an illegal character and causes 
immediate termination of the current line at that point, plus 
the output of an error flag in the assembly listing. For 
example: 

LABEL«-*A: MOV A,B 

Since the backarrow is not a recognized character, the entire 
line is treated as a: 

.WORD LABEL 

statement and is flagged in the listing. 
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2. A legal MACRO character may be illegal in context. Such a 
character generates a Q error on the assembly listing. 


5.2.1.3 

Operator Characters - 

Under MACRO, legal unary operators 

(operators applying to only one 

operand) 

are as follows s 

Unary 

Operator 

Explanation 


Example 

+ 

plus sign 

+A 

(positive value of A, 

equivalent to A) 

- 

minus sign 

-A 

(negative, 2*s complement, 
value of A) 

t 

uparrow, universal 

tF3.0 

(interprets 3.0 as a 


unary operator 


1-word floating-point 


(this usage is 
described in 


number) 


greater detail 
in Sections 

tC24 

(interprets the one's 


5.5.4.2 and 5.5.6.2). 


complement of the binary 

representation of 24(8)) 



tD127 

(interprets 127 as a decimal 
number) 



t034 

(interprets 34 as an octal 
number) 


tBllOOOlll (interprets 11000111 as a 
binary value) 

The unary operators described above can be used adjacent to each other 
in a term. For examples 

tCt012 

-t05 


Legal binary operators under MACRO are as follows: 


Binary 




Operator 

Explanation 


Example 

+ 

addition 

A+B 


- 

subtraction 

A-B 



* 

multiplication 

A*B 

(16-bit product returned) 

/ 

division 

A/B 

(16-bit quotient returned) 

& 

logical AND 

A&B 


l 

logical inclusive OR 

AIB 



All binary operators have the same priority. Division and 
multiplication are signed operations. Items can be grouped for 
evaluation within an expression by enclosure in angle brackets. Terms 
in angle brackets are evaluated first, and remaining operations are 
performed left to right. For examples 

9 WORD IIS il OCTAL 
.WORD U«2*3> IIS T OCTAL 
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5.2.2 Symbols 

There are three types of symbols: permanent, user-defined and . macro. 
MACRO maintains three types of symbol tables: the Permanent Symbol 
Table (PST), the User Symbol Table (UST) and the Macro Symbol Table 
(MST). The PST contains all the permanent symbols and is part of the 
MACRO Assembler load module. The UST and MST are constructed as the 
source program is assembled; user—defined symbols are added to the 
table as they are encountered. 


5.2.2.1 Permanent Symbols - Permanent symbols consist of the 
instruction mnemonics (Appendix C) and assembler directives and macro 
directives (sections 5.5 and 5.6, Appendix C)• These symbols are a 
permanent part of the assembler and need not be defined before being 
used in the source program. 


5.2.2.2 User-Defined and Macro Symbols - User-defined symbols are 
those used as labels or defined by direct assignment (Section 5.2.3)• 
These symbols are added to the User Symbol Table as they are 
encountered during the first pass of the assembly. Macro symbols are 
those symbols used as macro names in the operator field (Section 
5.6.1). These symbols are added to the Macro Symbol Table as they are 
encountered during the assembly. 

User-defined and macro symbols can be composed of alphanumeric 
characters, dollar signs, and periods only; any other character is 
illegal. 

The $ and . characters are reserved for system software symbols (for 
example, the system macro symbol .READ); it is recommended that $ and 
. not be inserted in user-defined or macro symbols. 

The following rules apply to the creation of user-defined and macro 
symbols: 

1. The first character must not be a number (except in the case 
of local symbols, see Section 5.2.5). 

2. Each symbol must be unique within the first six characters. 

3. A symbol can be written with more than six legal characters, 
but the seventh and subsequent characters are only checked 
for legality, and are not otherwise recognized by the 
assembler. 

4. Spaces, tabs, and illegal characters must not be embedded 
within a symbol. 

The value of a symbol depends upon its use in the program. A symbol 
in the operator field may be any one of the three symbol types. To 
determine the value of the symbol, the assembler searches the three 
symbol tables in the following order: 

1. Macro Symbol Table 

2. Permanent Symbol Table 

. User-Defined Symbol Table 
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A symbol found in the operand field is sought in the: 

1. User-Defined Symbol Table 

2. Permanent Symbol Table 

in that order. The assembler never expects to find a macro name in an 
operand field. 

These search orders allow redefinition of Permanent Symbol Table 
entries as user-defined or macro symbols. The same name can be 
assigned to both a macro and a label. 

User-defined symbols are either internal or external (global). All 
user-defined symbols are internal unless explicitly defined as being 
global with the .GLOBL directive (see Section 5.5.10). 

Global symbols provide links between object modules. A global symbol 
defined as a label is generally called an entry point (to a section 
of code). Such symbols are referenced from other object modules to 
transfer control throughout the load module (which may be composed of 
a number of object modules). 

Since MACRO provides program sectioning capabilities (Section 5.5.9) , 
two types of internal symbols must be considered: 

1. Symbols that belong to the current program section, and 

2. Symbols that belong to other program sections. 

In both cases, the symbol must be defined within the current assembly; 
the significance of the distinction is critical in evaluating 
expressions involving type (2) above (see Section 5.2.9). 


5.2.3 Direct Assignment 

A direct assignment statement associates a symbol with a value. When 
a direct assignment statement defines a symbol for the first time, 
that symbol is entered into the user symbol table and the specified 
value is associated with it. A symbol may be redefined by assigning a 
new value to a previously defined symbol. The latest assigned value 
replaces any previous value assigned to a symbol. 


The general format for a direct assignment statement is: 


symbol = expression 

Symbols take on the relocatable or absolute attribute of their 
defining expression. However, if the defining expression is global, 
the symbol is not global unless explicitly defined as such in a .GLOBL 
directive. For example: 

A*1 I THE SYMBOL * IS EQUATED TO THE 

IVALUE 1 


B»'A«UMASKL0W ITHE SYMBOL B IS EQUATED TO THE 
IVALUE OF THE EXPRESSION 


Cl 0*3 


ITHE SYMBOL D IS EQUATED TO 3 
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E; MOV #1 f ABLE JLABELS C AND E ARE EQUATED TO THE 

I LOCATION OF THE MOV COMMAND 

The following conventions apply to direct assignment statements: 

1. An equal sign (=) must separate the symbol from the 

expression defining the symbol value, 

2. A direct assignment statement is usually placed in the 
operator field and may be preceded by a label and followed by 
a comment. 


NOTE 

If the program jumps to or references 
the label of a direct assignment 
statement, it is actually referencing 
the following instruction statement. 
For example: 

*i* M 000 
Cl DO 

El MOV FDiABLE 

■ 

JMP C 

This code causes a jump to the label E, 


3. Only one symbol can be defined by any one direct assignment 
statement, 

4, Only one level of forward referencing is allowed. That is, 
the following arrangement is illegal: 

X = Y 

Y = Z 

Z = 1 

X and Y are both undefined throughout pass 1, X is undefined 
throughout pass 2 and causes an error flag in the assembly 
listing. 


5,2,4 Register Symbols 

The eight general registers of the PDP-11 are numbered 0 through 7 and 
can be expressed in the source program as: 

%0 

%1 


%7 
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The digit indicating the specific register can be replaced by any 
legal term which can be evaluated during the first assembly pass. 

It is recommended that the programmer create and use symbolic names 
for all register references. A register symbol may be defined in a 
direct assignment statement among the first statements in the program. 
A register symbol cannot be defined after the statement which uses it. 
The defining expression of a register symbol must be absolute. For 
example j 


R0*X0 I REGISTER DEFINITION 

R1 ■ % 1 

R2»%2 

R3* X3 

R4*%4 

R5PX5 

8P»Xb 

PC ■ X7 

The symbolic names assigned to the registers in the example above are 
the conventional names used in all PDP-11 system programs. Since 
these names are fairly mnemonic, it is suggested the user follow this 
convention. Registers 6 and 7 are given special names because of 
their special functions, while registers 0 through 5 are given similar 
names to denote their status as general purpose registers. 

All register symbols must be defined before they are referenced. A 
forward reference to a register symbol causes phase errors in an 
assembly. 

The % character can be used with any term or expression to specify a 
register. (A register expression less than 0 or greater than 7 is 
flagged with an R error code.) For example: 

CIR X3M 

is equivalent to: 

CIR X4 

and clears the contents of register 4, while: 

CLR 4 

clears the contents of memory address 4. 

In certain cases a register can be referenced without the use of a 
register symbol or register expression; these cases are recognized 
through the context of the statement. An example is shown below: 

JSR S# SUBR IFIRST OPERAND FIELD MUST ALWAYS 

I BE A REGISTER 


5.2.5 Local Symbols 

Local symbols are specially formatted symbols used as labels within a 
given range. 
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Local symbols provide a convenient means of generating labels to be 
referenced by branch instructions. Use of local symbols reduces the 
possibility of multiply-defined symbols within a user program and 
separates entry point symbols from local references. Local symbols, 
then, are not referenced from other object modules or even from 
outside their local symbol block. 

Local symbols are of the form n$, where n is a decimal integer from 1 
to 127, inclusive, and can only be used on word boundaries. Local 
symbols include: 

1 $ 

27$ 

59$ 

104$ 

Within a local symbol block, local symbols can be defined and 
referenced. However, a local symbol cannot be referenced outside the 
block in which it is defined. There is no conflict with labels of the 
same name in other local symbol blocks. 

Local symbols 64$ through 127$ can be generated automatically as a 
feature of the macro processor (see Section 5.6.3.5 for further 
details). When using local symbols the user is advised to first use 
the range from 1$ to 63$. 

A local symbol block is delimited in one of the following ways: 

1. The range of a single local symbol block can consist of those 
statements between two normally constructed symbolic labels. 
(Note that a statement of the form: 

LABEL=. 

is a direct assignment, does not create a label in the strict 
sense, and does not delimit a local range.) 

2. The range of a local symbol block is terminated upon 
encountering a .CSECT directive. 

3. The range of a single local symbol block can be delimited 

with .ENABL LSB and the first symbolic label or .CSECT 

directive following the .DSABL LSB directives. The default 
for LSB is off. 

For examples of local symbols and local symbol blocks, see Figure 5-1. 

The maximum offset of a local symbol from the base of its local symbol 
block is 128 decimal words. Symbols beyond this range are flagged 
with an A error code. 
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5,2,6 Assembly Location Counter 

The period (.) is the symbol for the assembly location counter. When 
used in the operand field of an instruction, it represents the address 
of the first word of the instruction. When used in the operand field 
of an assembler directive, it represents the address of the current 
byte or word. For example: 

AI MOV i•* R0 I 9 REFERS TO LOCATION A, 

fI•E 9 1 THE ADDRESS OF THE 
I MOV INSTRUCTION 


(# is explained in Section 5.4.9). 


At the beginning of each assembly pass, the assembler clears the 
location counter. Normally, consecutive memory locations are assigned 
to each byte of object data generated. However, the location where 
the object data is stored may be changed by a direct assignment 
statement altering the location counter: 

,=expression 

The expression defining the location counter must not contain forward 
references or symbols that vary from one pass to another. If an 
expression is assigned to the current location counter in a 
relocatable CSECT, an error flag is generated. (The construction 
.=.+expression must be used.) 

Similar to other symbols, the location counter symbol has a mode 
associated with it, either absolute or relocatable; the mode cannot 
be external. The existing mode of the location counter cannot be 
changed by using a defining expression of a different mode. 
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Line Octal 

Number Expansion 


Source Code 


Comments 


1 

2 

3 

4 

5 

6 

7 0(90000 

8 000000 

9 

10 
11 

12 00000 


000000 

000000 * 


IMPURei 


.MCALL .REGDEF,,, v?,• 

.REGDEF 
»•V2. . 

R0«X0 

,SBTTl SECTOR INITIALIZATION 

•CSECT IMPURE lIMPURE STORAGE AREA 


13 

U 

15 

00000 

000000* 

IMPPASI 

000000* 

.CSECT 

.CSECT IMPPAS 

IMPLIN 

tCLEARED each PASS 

icleared EACH line 

16 

17 

00000 

IMPLINI 

000000* 

.CSECT 

XCTPRG 

IPROGRAM 

18 

19 

20 

00000 

00000 

xctprgi 

012700 

MOV 

•IMPURE,R0 

1 INITIALIZATION 

21 

00004 

000000* 

005020 1SI 

CLR 

(R0) + 

1 CLEAR IMPURE AREA 

22 

00006 

022700 

CMP 

#IMPTOP,R0 


23 

00012 

000000* 

101374 

BHI 

IS 


24 

25 


000000* 

.CSECT 

XCTPA3 

1PASS initialization 

26 

27 

00000 

00000 

XCTPA8I 

012700 

MOV 

#IMPPAS,R0 

28 

00004 

000000* 

005020 1SI 

CLR 

(R0) * 

i clear impure part 

29 

00006 

022700 

CMP 

•IMPTOP,R0 

30 

31 

32 

00012 

000000* 

101374 

BHI 

IS 



000000* 

.CSECT 

XCTLIN 

ILINE INITIALIZATION 

33 

34 

00000 

00000 

XCTLINI 

012700 

MOV 

•IMPLIN,R0 

35 

00004 

000000* 

005020 IS! 

CLR 

(R0) * 


36 

00006 

022700 

CMP 

*IMPTOP,R0 


37 

00012 

000000* 

101374 

BHI 

IS 


38 

39 


000000* 

.CSECT 

MIXED 

tMIXED MODE SECTOR 

40 

«1 

00000 

000000 imptopi 
000001 * 

.WORD 0 
.END 



Figure 5-1 

Assembly Source Listing of MACRO Code Showing Local Symbol Blocks 
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The mode of the location counter symbol can be changed by the use of 
the .ASECT or .CSECT directive as explained in Section 5.5.9. 

Examples: 

.ASECT 

,■500 >SET LOCATION COUNTER TO 

IABSOLUTE 500 

FIRSTI MOV ,*10,COUNT > THE LABEL FIRST HAS THE VALUE 

>500(6) 

>,♦10 EQUALS 510(8), THE 
>C0NTENT3 OF THE LOCATION 
>510(8) WILL BE DEPOSITED 
>IN LOCATION COUNT, 

>THE ASSEMBLY LOCATION COUNTER 
)NOW HAS A VALUE OF 
>ABSOLUTE 520(8), 

> THE LABEL SECOND HAS THE 
>VALUE 520(8) 

>THE CONTENTS OF LOCATION 
>520(8), THAT IS, THE BINARY 
>C00E FOR THE INSTRUCTION 
>itself will BE 0EP0SITE0 IN 
>LOCATION INDEX, 


>SET LOCATION COUNTER TO 
RELOCATABLE 20 OF THE 
>UNNAMED PROGRAM SECTION, 

>THE LABEL THIRD HAS THE 
>VALUE OF RELOCATABLE 20, 

Storage area may be reserved by advancing the location counter. For 
example, if the current value of the location counter is 1000, the 
direct assignment statement: 

,■,♦100 

reserves 100(octal) bytes of storage space in the program. The next 
instruction is stored at 1100. (The .BLKW and .BLKB directives can 
also be used to reserve blocks of storage; see Section 5.5.5.3.) 


COUNT! ,WORD 0 
,■520 

SECOND! MOV ,,INDEX 

INDEX! .WORD 0 

,C»ECT 
.■•♦20 

THIRD! .WORD 0 
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5.2,7 Numbers 


The MACRO Assembler assumes all numbers in the source program are to 
be interpreted in octal radix unless otherwise specified. The assumed 
radix can be altered with the .RADIX directive or individual numbers 
can be treated as being of decimal, binary, or octal radix (see 
Section 5.5.4.2). 

Octal numbers consist of the digits 0 through 7 only. A number not 
specified as a decimal number and containing an 8 or 9 is flagged with 
an N error code and treated as a decimal number. 

Negative numbers are preceded by a minus sign (the assembler 
translates them into two's complement form). Positive numbers may be 
preceded by a plus sign, although this is not required. 

A number which is too large to fit into 16 bits (177777<n) is 
truncated from the left and flagged with a T error code in the 
assembly listing. 

Numbers are always considered absolute quantities (that is, not 
relocatable). 

The single-word floating-point numbers which can be generated with the 
tF operator (see Section 5.5.6.2) are stored in the following formats 


15 14 


SIGN 

BIT 


8-BIT EXPONENT 


7-BIT MANTISSA 


Refer to PDP-11/45 Processor Handbook for details of the 
floating-point format. 


5.2.8 Terms 

A term is a component of an expression. A term may be one of the 
followings 

1. A number whose 16-bit value is used. 

2. A symbol that is interpreted according to the following 

hierarchys 

a. a period that causes the value of the current location 
counter to be used 

b. a permanent symbol whose basic value is used and whose 
arguments (if any) are ignored 

c. user defined symbols 

d. an undefined symbol that is assigned a value of zero and 
inserted in the user-defined symbol table 
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3. An ASCII conversion using either an apostrophe followed by a 
single ASCII character or a double quote followed by two 
ASCII characters, which results in a word containing the 
7-bit ASCII value of the character(s). (This construction is 
explained in greater detail in Section 5.5.3.3.) 

4. An expression enclosed in angle brackets. Any quantity 
enclosed in angle brackets is evaluated before the remainder 
of the expression in which it is found. Angle brackets are 
used to alter the left to right evaluation of expressions 
(for example, to differentiate between A*B+C and A*<B+C>) or 
to apply a unary operator to an entire expression (-<A+B>). 


5.2.9 Expressions 

Expressions are combinations of terms that are joined together by 
binary operators and that reduce to a 16-bit value. The operands of a 
.BYTE directive are evaluated as word expressions before truncation to 
the low-order eight bits. Prior to truncation, the high-order byte 
must be zero or all ones (when the byte value is negative, the sign 
bit is propagated). The evaluation of an expression includes the 
evaluation of the mode of the resultant expression——that is, absolute, 
relocatable or external. Expression modes are defined further below. 

Expressions are evaluated left to right with no operator hierarchy 
rules except that unary operators take precedence over binary 
operators. A term preceded by a unary operator can be considered as 
containing that unary operator. (Terms are evaluated, where 
necessary, before their use in expressions.) Multiple unary operators 
are valid and are treated as follows: 


—+—A 

is equivalent to: 

-<+<-A>> 

The value of an external expression is the value of the absolute part 
of the expression; e.g., EXT+A has a value of A. This is modified by 
the Linker to become EXT+A. 

Expressions, when evaluated, are either absolute, relocatable, or 
external. For the programmer writing position independent code, the 
distinction is important. 

1. An expression is absolute if its value is fixed. An 

expression whose terms are numbers and ASCII conversions has 
an absolute value. A relocatable expression minus a 
relocatable term, where both items belong to the same program 
section, is also absolute. 

2. An expression is relocatable if its value is fixed relative 
to a base address but will have an offset value added when 
linked. Expressions whose terms contain labels defined in 
relocatable sections and the assembly location counter (in 
relocatable sections) have a relocatable value. 

An expression is external (or global) if its value is only 
partially defined during assembly and is completed at link 
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time. An expression whose terms contain a global symbol not 
defined in the current program is an external expression. 
External expressions have relocatable values at execution 
time if the global symbol is defined as being relocatable or 
absolute if the global symbol is defined as absolute. 

An example of the three expression types follows: 


. ASECT 

.•100 

ABSSYM*, 

ITHE VALUE Of ABSSYM IS 

1 NOT RELOCATABLE. BECAUSE 

1 WE ARE IN AN ASECT 

.CSECT MAIN 

1 START RELOCATABLE 

IPROGRAM SECTION 

.GLQBL EXTVAL 

IEXTVAL IS DEFINED ELSEWHERE. 
1 ITS VALUE will not BE KNOWN 

1 UNTIL LINK TIME 

BESSYMI .BIKW U 

.ASCII ✓ABCD/ 

.EVEN 

ENDSYM». 

ITHE VALUES Of BEGSYM 

I AND ENDSYM ARE 

1 RELOCATABLE. BECAUSE 

ITHE ADDRESS AT WHICH 
|"MAIN" WILL BE LOADED 

IIS NOT DETERMINED UNTIL 

ILINK TIME 

SIZE ■ endsym-begsym 

IHOWEVER, THE 

1 VALUE OF SIZE IS KNOWN 

1 CIT IS 12.)AT ASSEMBLY 

1 TIME AND IS ABSOLUTE 

RELEXP ■ ENDSYM-BEGSYM*. 

IRELEXP (•.♦12.) IS 

irelocatable 

EXTEXPI .W0R0 EXTVAL*« 

ITHE EXPRESSION "EXTVAL*«" 

IIS EXTERNAL (OR GLOBAL) 
IBECAUSE EXTVAL IS DEFINED 

1IN ANOTHER program unit. 

CHARA* * A 

ITHE VALUE of chara 

IIS ABSOLUTE 

5.3 RELOCATION AND LINKING 



The output of the MACRO Assembler is an object module which must be 
processed by LINK before loading and execution (refer to Chapter 6 for 
details). The Linker essentially fixes (i.e., makes absolute) the 
values of external or relocatable symbols and turns the object module 
into a load module. 

To enable the Linker to fix the value of an expression , the assembler 
issues certain directives to the Linker together with required 
parameters. In the case of relocatable expressions, the Linker adds 
the base of the associated relocatable section (the location in memory 
of relocatable 0) to the value of the relocatable expression provided 
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by the assembler. In the case of an external expression, the value of 
the external term in the expression is determined by the Linker (since 
the external symbol must be defined in one of the other object modules 
which are being linked together) and adds it to the value of the 
external expression provided by the assembler. 

All words that are to be modified (as described in the previous 
paragraph) are marked with an apostrophe in the assembly listing. A G 
in the listing indicates that the value is external, or that a global 


is added 
follows: 

to that 

value. Thus, the binary text output looks as 

005065 

000000G 

Cl* 

EXTERNAL(R5) 

fVALUE OF EXTERNAL SYMBOL 

/ ASSEMBLED ZERO) MILL BE 

1 MODIFIED BY THE LINKER, 

005065 

000006G 

CUR 

EXTERNAU+6CR5) 

ITHE ABSOLUTE PORTION OF THE 

/EXPRESSION (000006) IS AOOEO 
/BY THE LINKER TO THE VALUE OF 
/THE EXTERNAL SYMBOL 

005065 

CUP 

REU0CATABUE(R5) 

/ASSUMING WE ARE IN A 


000040 

I RELOCATABLE SECTION 
I AND THi VALUE OF RELOCATABLE 
IIS RELOCATABLE 40 


5.4 ADDRESSING MODES 

The program counter (PC, register 7 of the eight general registers) 
always contains the address of the next word to be fetched; i.e., the 
address of the next instruction to be executed, or the second or third 
word of the current instruction. 

In order to understand how the address modes operate and how they 
assemble, the action of the program counter must be understood. The 
key rule is: 

Whenever the processor implicitly uses the program counter 
to fetch a word from memory, the program counter is 

automatically incremented by two after the fetch. 

That is, when an instruction is fetched, the PC is incremented by two 
so that it is pointing to the next word in memory; if an instruction 
uses indexing (Sections 5.4.7, 5.4.9 and 5.4.11) the processor uses 

the program counter to fetch the base from memory. Hence, using the 

rule above, the PC increments by two, and now points to the next word. 

The following conventions are used in this section: 

1. Let E be any expression as defined in Section 5.2. 

2. Let R be a register expression. This is any expression 

containing a term preceded by a % character or a symbol 
previously equated to such a term. 
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Examples: 

R0>X0 I GENERAL REGISTER 0 
R1■R0 +1 I GENERAL REGISTER 1 
R2M+XI f GENERAL REGISTER 2 

3. Let ER be a register expression or an expression in the range 
0 to 7 inclusive, 

4. Let A be any general address specification which produces a 
6-bit mode address field as described in Sections 3.1 and 3.2 
of the PDP-11 PROCESSOR HANDBOOK (both 11/20 and 11/45 
versions). 

The addressing specifications , A, can be explained in terms of E, R # 
and ER as defined above. Each is illustrated with the single operand 
instruction CLR or double operand instruction MOV. 


5.4.1 Register Mode 
The register contains the operand. 
Format for A: R 

Examples: R0«X0 

CL* R0 


IDEFINE R0 A3 REGISTER 0 
ICLEAR REGISTER 0 


5.4.2 Register Deferred Mode 

The register contains the address of the operand. 

Format for A: @R or (ER) 

Examples: CL* RR1 I BOTH INSTRUCTIONS CLEAR 

ITHE WORD AT THE AOORESS 
CLR (Rt) ICONTaINEO IN REGISTER 1 

5.4.3 Autoincrement Mode 

The contents of the register are incremented immediately after being 
used as the address of the operand. (See NOTE below.) 
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Format for As 

(ER) + 



Examples s 

el* 

CL* 

CLK 

(R0) ♦ 
(R0+3)♦ 
(R3) ♦ 

fEACH INSTRUCTION CLEARS 

1 THE WORD AT THE ADDRESS 
ICONTAINED in THE SPECIFIED 

iregister and increments 

ITHAT REGISTER'S CONTENTS 
IBY TWO, 


CL.KB 

(R«) + 

iclears the byte at the 

1 ADDRESS SPECIFIED BY THE 

1CONTENTS OF Rfl AND 
IINCREMENTS R4 BY ONE, 



NOTE 


Both JMP 

and 

JSR instructions using 


non-deferred autoincrement mode, 
autoincrement the register before its 
use on the PDP-11/20 and 11/05 (but not 
on the PDP-11/40 or 11/45). In double 
operand instructions of the addressing 
form %R,(R) + or %R,-(R) where the source 
and destination registers are the same, 
the source operand is evaluated as the 
autoincremented or autodecremented 
value, but the destination register, at 
the time it is used, still contains the 
originally intended effective address. 


In the following two examples, as 
executed on the PDP-11/20, R0 originally 
contains 100, 


moy 

R0,CRB)♦ 

|THE QUANTITY 
JTO LOCATION 

10? 

100 

IS MOVED 

MOV 

R0,*(R0) 

)THE QUANTITY 
ITO LOCATION 

76 

76 

IS MOVED 


The use of these forms should be avoided 
as they are not compatible with the 
PDP-11/05, 11/40 and 11/45, 

A Z error code is printed with each instruction which is not 
compatible among all members of the PDP-11 family. This is merely a 
warning code. 


5.4,4 Autoincrement Deferred Mode 

The register contains the pointer to the address of the operand. The 
contents of the register are incremented after being used. 
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Format for A: <?(FR) + 

Example: CL# #(R3W ICONTENTS OF REGISTER 3 POINT 

no address of word to be 

I CLEARED# AN0 REGISTER 3 IS 
I THEN INCREMENTED BY TWO 


5.4.5 Autodecrement Mode 


The contents of the register are decremented before being used as the 
address of the operand (see NOTE under autoincrement mode). 


Format for As 

-(ER) 

Examples s 

CL* 


CL* 


CL* 


•(R0) t DECREMENT CONTENTS OF 
•(R0«-3) 10 , 3, ANO 2 BY Two 
• (R2) f BEFORE USING AS ADDRESSES 

t OF WORDS TO BE CLEARED, 


5.4.C Autodecrement Deferred 'lode 


The contents of the register are decremented before being used as the 
pointer to the address of the operand. 


Format for A: (ER) 


Example: CL# #-(R2) I DECREMENT CONTENTS OF 

IREGISTER 2 BY TWO BEFORE 
»USING AS A pointer 
I TO ADDRESS OF word To be 
icleared. 


5.4.7 Index Mode 

The value of an expression E is stored as the second or third word of 
the instruction. The effective address is calculated as the value of 
E plus the contents of register ER. The value E is called the base. 

Format for A: E(ER) 

Examples: CL« CRl) fEFFECTIVE ADDRESS IS X+2 PLUS 

I THE CONTENTS OF REGISTER 1 
CL* *2(R3) fEFFECTIVE ADDRESS IS «2 PLUS 

>THE CONTENTS OF REGISTER 3, 


5.4.8 Index Deferred Mode 

An expression plus the contents of a register gives the pointer to the 
address of the operand. 
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Format for A: @E(ER) 

Example: #14(R4) lIF REGISTER 4 HOLDS 100 AND 

I LOG 114 HOLDS 2000, 
ILOCATION 2000 IS cleared. 


5,4.9 Immediate Mode 

The immediate mode allows the operand itself to be stored as the 
second or third word of the instruction. It is assembled as an 
autoincrement of register 7, the PC. 

Format for A: #E 

Examples: MOV #100,R0 |MOVE AN OCTAL 100 TO 

IREGISTER 0 

MOV #X,R0 IMOVE THE VALUE OF THE SYMBOL X TO 
I REGISTER 0 

The operation of this mode can be explained by the following example. 
The statement MOV #100,R3 assembles as two words. These are: 

012703 

000100 

Just before this instruction is fetched and executed, the PC points to 
the first word of the instruction. The processor fetches the first 
word and increments the PC by two. The source operand mode is 27 
(autoincrement the PC). Thus, the PC is used as a pointer to fetch the 
operand (the second word of the instruction) before being incremented 
by two, to point to the next instruction. 


5.4.10 Absolute Mode 


Absolute mode is the equivalent of immediate mode deferred. @#E 
specifies an absolute address which is stored in the second or third 
word of the instruction. Absolute mode is assembled as an 
autoincrement deferred of register 7, the PC. 

Format for A: @#E 


Examples: MOV 

CL* 


##100,R0 IMOVE THE VALUE OF contents 
I OF LOCATION 100 TO 
IREGISTER 0. 

##X I CLEAR THE CONTENTS OF THE 

ILOCATION WHOSE A0DRESS IS X, 


5.4.11 Relative Mode 

Relative mode is the normal mode for memory references. 
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Format for A: E 



Examples: ClR 

100 

1 CLEAR LOCATION 100 

MOV 

*,V 

IM0V THE CONTENTS OF LOCATION X 


fTO LOCATION Y, 

Relative mode is assembled as index mode, using register 7, the PC, as 
the index register. The base of the address calculation, which is 
stored in the second or third word of the instruction, is not the 
address of the operand (as in index mode), but the number which, when 
added to the PC, becomes the address of the operand. Thus, the base 
is X-PC, which is called an offset. The operation is explained as 
follows: 

If the statement MOV 100,R3 is assembled at absolute location 20, the 
assembled code is: 

Location 20: 016703 

Location 22: 000054 

The processor fetches the MOV instruction and adds two to the PC so 
that it points to location 22. The source operand mode is 67, that is, 
indexed by the PC. To pick up the base, the processor fetches the 
word pointed to by the PC and adds two to the PC. The PC now points 
to location 24. To calculate the address of the source operand, the 
base is added to the designated register, that is, BASE+PC=54+24=100, 
the operand address. 

Since the assembler considers "." as the address of the first word of 
the instruction, an equivalent index mode statement would be: 

MOV 100-.-4(PC),R3 

This mode is called relative because the operand address is calculated 
relative to the current PC. The base is the distance or offset (in 
bytes) between the operand and the current PC. If the operator and 
its operand are moved in memory so that the distance between the 
operator and data remains constant, the instruction will operate 
correctly anywhere in memory. 


5.4.12 Relative Deferred Mode 

Relative deferred mode is similar to relative mode, except that the 
expression, E, is used as the pointer to the address of the operand. 

Format for A: @E 

Example: MOV #X,R0 |MOVE THE CONTENTS OF THE 

I LOCATION WHOSE ADDRESS IS IN 
IX INTO REGISTER 0 


5.4.13 Table of Mode Forms and Codes 

Each instruction assembles into at least one word. Operands of the 
first six forms listed below do not increase the length of an 
instruction. Each operand in one of the other modes, however, 
increases the instruction length by one word. 
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Form 

Mode 

Meaning 

R 

On 

Register mode 

@R or (ER) 

In 

Register deferred mode 

(ER) + 

2n 

Autoincrement mode 

@ (ER) + 

3n 

Autoincrement deferred mode 

-(ER) 

4n 

Autodecrement mode 

(ER) 

5n 

Autodecrement deferred mode 

n represents the register number. 

Any of the following forms adds one word to the instruction length: 

Form 

Mode 

Meaning 

E (ER) 

6n 

Index mode 

@E (ER) 

7n 

Index deferred mode 

#E 

27 

Immediate mode 

@#E 

37 

Absolute memory reference mode 

E 

67 

Relative mode 

@E 

77 

Relative deferred reference mode 


n represents the register number. Note that in the last four forms, 
register 7 (the PC) is referenced. 

NOTE 

An alternate form for @R is (ER) . 

However, the form @(ER) is equivalent to 
@0 (ER) . 

The form @#E differs from the form E in 
that the second or third word of the 
instruction contains the absolute 
address of the operand rather than the 
relative distance between the operand 
and the PC. Thus, the instruction 
CLR @#100 clears absolute location 100 
even if the instruction is moved from 
the point at which it was assembled. 

See the description of the .ENABL AMA 
function in Section 5.5.2, which directs 
the assembly of all relative mode 
addresses as absolute mode addresses. 


5.4.14 Branch Instruction Addressing 

The branch instructions are 1-word instructions. The high byte 
contains the op code and the low byte contains an 8-bit signed offset 
which specifies the branch address relative to the PC. Upon execution 
of a branch instruction, the hardware calculates the branch address as 
follows: 

1. Extend the sign of the offset through bits 8-15. 

2. Multiply the result by 2. This creates a word offset rather 
than a byte offset. 
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3. Add the result to the PC to form the final branch address. 

The assembler performs the reverse operation to form the byte offset 
from the specified address. Remember that when the offset is added to 
the PC, the PC is pointing to the word following the branch 
instruction; hence the term —2 in the calculation. 

Byte offset = (E-PC)/2 truncated to eight bits. 

Since PC = .+2, we have: 

Byte offset = (E-.-2)/2 truncated to eight bits. 

NOTE 

It is illegal to branch to a location 
specified as an external symbol, or to a 
relocatable symbol from within an 
absolute section, or to an absolute 
symbol or a relocatable symbol or 
another program section from within a 
relocatable section. 


5.4.15 EMT and TRAP Addressing 

The EMT and TRAP instructions do not use the low-order byte of the 
word. This allows information to be transferred to the trap handlers 
in the low-order byte. If EMT or TRAP is followed by an expression, 
the value is put into the low-order byte of the word. However, if the 
expression is too big (>377(8)) it is truncated to eight bits and a T 
error flag is generated. 


5.5 ASSEMBLER DIRECTIVES 

Directives are statements which cause the assembler to perform certain 
processing operations. 

Assembler directives can be preceded by a label, subject to 
restrictions associated with specific directives, and followed by a 
comment. An assembler directive occupies the operator field of a 
MACRO source line. Only one directive can be placed on any one line. 
Zero, one, or more operands can occupy the operand field; legal 
operands differ with each directive and may be either symbols, 
expressions, or arguments. 


5.5.1 Listing Control Directives 


5.5.1.1 .LIST and .NLIST - Listing options can be specified in the 
text of a MACRO program through the .LIST and .NLIST directives. 
These are of the form: 

.LIST arg 
.NLIST arg 
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where arg represents one or more optional arguments. When used 
without arguments, the listing directives alter the listing level 
count. The listing level count causes the listing to be suppressed 
when it is negative. The count is initialized to zero, incremented 
for each .LIST and decremented for each .NLIST. For example: 

.list he 

.MACRO LTEST (LIST TEST 
M»TH|S LINE SHOULD LIST 
.NLIST 

»b*this line SHOULD NOT LIST 
.NLIST 

»C»THIS LINE SHOULD NOT LIST 
.LI8T 

JO-THIS LINE SHOULD NOT LIST (LEVEL NOT BACK TO ZERO) 

.LIST 

»e*this line SHOULD list (LEVEL BACK TO ZERO) 

.ENOM 

ITEST icall the macro 

M*THIS LINE SHOULD list 

|E»ThiS line SHOUlo list (LEVEL back TO ZERO) 

The primary purpose of the level count is to allow macro expansions to 
be selectively listed and yet exit with the level returned to the 
status current during the macro call. 

The use of arguments with the listing directives does not affect the 
level count; however, .LIST and .NLIST can be used to override the 
current listing control. For example: 

.MACRO XX 


.LIST »LIST NEXT LINE 

*■. 

.NLIST IDO NOT LIST REMAINDER 

i of macro expansion 


,endm 

.NLIST ME 100 NOT LIST MACRO EXPANSIONS 

XX 

*■. 


Allowable arguments for use with the listing directives are as follows 
(these arguments can be used singly or in combination): 


Argument 

Default 

Function 


SEQ 

list 

Controls the listing of 
sequence numbers. 

source line 

LOC 

list 

Controls the listing of 
counter (this field would 
be suppressed), 

the location 
not normally 

BIN 

list 

Controls the listing of generated binary 
code (supersedes BEX)• 
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BEX 


SRC 

COM 


MD 


MC 


ME 


MEB 


CND 


LD 


TOC 


TTM 


SYM 


list 


list 

list 

list 

list 

no list 

no list 


list 


no list 


list 


Terminal 

mode 


list 


Controls listing of binary extensions; 
that is, prevents listing those 
locations and binary contents beyond the 
first line of an expansion. This is a 
subset of the BIN argument. 

Controls the listing of the source code. 

Controls the listing of comments. This 
is a subset of the SRC argument and can 
be used to reduce listing time and/or 
space where comments are unnecessary. 

Controls listing of macro definitions 
and repeat range expansions (has no 
effect in ASEMBL). 

Controls listing of macro calls and 
repeat range expansions (has no effect 
in ASEMBL). 

Controls listing of macro expansions 
(supersedes MEB; has no effect in 
ASEMBL) . 

Controls listing of macro expansion 
binary code. A .LIST MEB causes only 
those macro expansion statements 
producing binary code to be listed. 
This is a subset of the ME argument (has 
no effect in ASEMBL). 

Controls the listing of unsatisfied 
conditions and all .IF and .ENDC 
statements. This argument permits 
conditional assemblies to be listed 
without including unsatisfied code. 

Controls listing of all listing 
directives having no arguments (those 
used to alter the listing level count)• 

Controls listing of table of contents on 
pass 1 of the assembly (see Section 
5.5.1.4 describing the .SBTTL 
directive). The full assembly listing is 
printed during pass 2 of the assembly. 

Controls listing output format (has no 
effect in ASEMBL). The TTM argument (the 
default case) causes output lines to be 
truncated to 72 characters. Binary code 
is printed with the binary extensions 
below the first binary word. The 
alternative (.NLIST TTM) to Terminal 
mode is line printer mode, which is 
shown in Figure 5-2. 

Controls the listing of the symbol table 
for the assembly. 
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An example of an assembly listing as sent to a 132-column line printer 
is shown in Figure 5-2. Notice that binary extensions for statements 
generating more than one word are spread horizontally on the source 
line. An example of an assembly listing as sent to an 80-column line 
X^rinter is shown in Figure 5-3 (this is the same format as a terminal 
listing). Notice that binary extensions for statements generating more 
than one word are printed on subsequent lines. 

Figure 5-4 illustrates a symbol table listing. With the exception of 
local symbols and macro names, all user-defined symbols are listed in 
the symbol table. The characters following the symbols listed have 
special meanings as follows: 

= the symbol is assigned in a direct assignment 

statement 

% the symbol is a register symbol 

R the symbol is relocatable 

G the symbol is global 

The final value of the symbol is expressed in octal. If the symbol is 
undefined six asterisks are printed in place of the octal number. 

CSECT numbers are listed if the symbol is in a named CSECT. All 
CSECTs are listed at the end of the table with their lengths and 
corresponding number. 
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RTEXEC RT-11 MACRO VM02-09 5-SEP-74 22«30»23 PAGE 29+ 

SYMBOL TABLE 


ABSEXPs ****** G 


ARGCMTa 

****** G 


ASSEM s 

****** G 


BINCHNs 000004 


BINDAT 

002322R 

004 

BLKTBLs 

002310R 

00a 

BPMB s 000020 


BUFTBL 

000374RG 

003 

CHAN 

002362R 

00a 

CHMSPC 000312R 

003 

CHRPNTs 

****** G 


CLK50 = 

000040 


CMILENs 000123 


cnttbl 

000360RG 

003 

CONFIG* 

000300 


CONT 000040RG 

010 

CORERR 

001726R 

010 

CPL * 

000120 


CR a 000015 


CRFBUF 

002076RG 

004 

CRFC * 

000040 


CRFCHNa 000012 


crfcnt 

00000URG 

007 

crfdat 

002352R 

00a 

CRFE a 000100 


CRFFLG 

000000R 

007 

CRFLENs 

000204 


CRFM a 000010 


CRFP a 

000020 


crfpnt 

000064R 

003 

CRFR s 000004 


CRFS a 

000002 


CRFSPC 

000114R 

003 

CRFTAB 000026R 

003 

CRFTST 

000002RG 

007 

CSIERR 

000214R 

003 

CTLTBL 000000R 

003 

DATE 

001000R 

010 

DATUM 

001004RG 

00a 

DEFEXT 000104R 

003 

DEVFUL 

000252R 

003 

DI V6C?i 

001240R 

010 

DNC a ****** G 


EDMASKa 

****** G 


ED.ABS* 

****** G 


EMTERRa 000052 


ENDP1 a 

****** G 


ENDP2 * 

****** G 


ENDSWT 000434R 

010 

ERR 

001662R 

010 

ERRB 

000102R 

010 

ERRBTSa ****** G 


ERRCNTa 

****** G 


EXMFLG* 

****** G 


FF a 000014 


FILNF 

000264R 

003 

FIN 

001434RG 

010 

FINCL 001636R 

010 

FINMSG 

001030R 

009 

FINMS1 

001052R 

00a 

FINMS2 001070R 

004 

finpi 

000776R 

010 

FINP2 

000776R 

010 

FINSML 002124RG 

010 

frecor 

0 0 0 0 0 6R 

007 

GETPLI 

001756RG 

010 

GETR50a ****** G 


GS ARG a 

****** G 


hdrttl 

001102RG 

00a 

HIGHADa 000050 


ILLCMD 

000226R 

003 

ILLDEV 

000240R 

003 

IMPURT 000042R 

• 

• 

007 

IMPURS 

000000R 

007 

INI OF 

000106R 

010 

• 

RTEXEC RT-11 M A C R C 

) VM02-09 5- 

■SEP-74 22 J 30 I 23 
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TIME 000210R 

003 

TIMTIM 

001016R 

004 

TI MtoRD 

000204R 

003 

TMPCNTa 000014 


TSTSTK 

001704RG 

010 

ttlbrk* 

****** G 


TTLBUFa ****** G 


TTLLENa 

000040 


TTYBUF* 

000616 


USRLOCa 000046 


VT a 

000013 


WINST = 

104240 


WRTERR 002306R 

010 

XBAW a 

000000 


XEDPIC* 

000000 


XMIT0 a ****** G 


SCLOUT 

003006RG 

010 

SEDABL* 

****** G 


SFLUSH 002732RG 

010 

SNLISTa 

****** G 


SREAD 

002422RG 

010 

SREADW 002422RG 

010 

SWA IT 

002730RG 

010 

SWRITE 

002134RG 

010 


SWRITW 002134RG 010 


. ABS. 

000000 

000 


000000 

001 

OPURE 

000000 

002 

DPURES 

000ai0 

003 

MIXEOS 

002376 

004 

SWTSES 

000000 

005 

SWTSEC 

000000 

006 

IMPURS 

0000a2 

007 

maims 

003024 

010 

ERRORS 

DETECTED: 

0 


FREE COREt 13431. WORDS 


#LPl/C/L»BEX*RP4lRTPAR,RPARAM,RCI0CH,RTEXEC 


Figure 5-4 
Symbol Table 


5-33 




MACRO Assembler 


5.5.1.2 Page Headings - The MACRO Assembler outputs each page in the 
format shown in Figure 5-3. On the first line of each listing page the 
assembler prints (from right to left): 

1. title taken from .TITLE directive (most recent one 

encountered) 

2. assembler version identification 

3. the date and time of day if entered 

4. page number 

The second line of each listing page contains the subtitle text 
specified in the last encountered .SBTTL directive. 


5.5.1.3 .TITLE - The .TITLE directive is used to print a heading in 
the output listing and to assign a name to the object module. The 
heading printed on the first line of each page of the listing is taken 
from the first 31 characters of the argument in the .TITLE directive. 
The first six characters (symbol name) of this same line are also used 
as the name of the object module. These six characters must be 
Radix-50 characters (any characters beyond the first six are ignored). 
Non-Radix-50 characters are not acceptable. 

For example: 

.TITLE PROG TO PERFORM DAILY ACCOUNTING 

causes PROG TO PERFORM DAILY ACCOUNTIN to be printed in the heading 
for each page and causes the object module of the assembled program to 
be PROG (this name is distinguished from the filename of the object 
module specified in the command string to the assembler). 

If there is no TITLE statement, the default name assigned to the first 
object module is: 

.MAIN, 

The first tab or space following the .TITLE directive is not 
considered part of the object module name or header text, although 
subsequent tabs and spaces are significant. 

If there is more than one .TITLE directive, the last .TITLE directive 
in the program conveys the name of the object module. 


5.5.1.4 .SBTTL - The .SBTTL directive is used to provide the 
elements for a printed table of contents of the assembly listing. The 
text following the directive is printed as the second line of each of 
the following assembly listing pages until the next occurrence of a 
.SBTTL directive. 

For example: 

.SBTTL CONDITIONAL ASSEMBLIES 
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The text: 


CONDITIONAL ASSEMBLIES 

is printed as the second line of each of the following assembly 
listing pages. 

During pass 1 of the assembly process, MACRO automatically prints a 
table of contents for the listing containing the line sequence number 
and text of each .SBTTL directive in the program. Such a table of 
contents is inhibited by specifying the .NLIST TOC directive within 
the source. 

An example of a table of contents is shown in Figure 5-5. 


.MAIN, RT-11 macro VM02-09 5-SEP-74 22:30:23 

table OF contents 


1- 29 
1* 37 

2 - 1 

3- 1 

4- 1 

5- 1 

7- 1 

10 * 1 

11- 2 

12- 2 

13- 1 

14- 1 

15- 1 

16- 1 

17- 1 

16- 1 

19- 1 

20 - 1 
21 - 1 
22 - 1 

23- 1 

24- 1 

25- 1 

26 - 1 

27- 1 

29- 1 


RT-11 MACRO PARAMETER FILE 
COMMON PARAMETER FILE 

ASSEMBLY OPTIONS 
VARIABLE PARAMETERS 

globals 

SECTOR INITIALIZATION 
SUBROUTINE CALL DEFINITIONS 
MISCELLANEOUS MACRO DEFINITIONS 
MCIOCH - I/O CHANNEL ASSIGNMENTS 
****EXEC**** 

PROGRAM START 
INIT OUTPUT FILES 
SWITCH HANDLERS 
END-OF-PASS ROUTINES 
SWITCH AND DATE DATA areas 
INIT OUTPUT FILES (CONTINUED) 

FINISH ASSEMBLY AND RESTART 

MEMORY MANAGEMENT 

GET PHYSICAL SOURCE LINE 

SYSTEM MACRO HANDLERS 

WRITE ROUTINES 

READ ROUTINE 

COMMON I/O ROUTINES 

MESSAGES 

I/O TABLES 

FINIS 


Figure 5-5 

Assembly Listing Table of Contents 


Table of Contents text is taken from the text of each .SBTTL 
directive. The associated numbers are the page and line numbers of 
the .SBTTL directives. 
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5.5.1.5 .IDENT - The .IDENT directive is not used or supported by 
the RT-11 system, but is handled by MACRO for compatibility with other 
systems. .IDENT provides a means of labeling the object module 
produced as a result of a MACRO assembly. In addition to the name 
assigned to the object module with the .TITLE directive, a character 
string (up to six characters, treated like a .RAD50 string) can be 
specified between paired delimiters. For examples 

.IDENT AO05A/ 

The character strings 

V005A 

is converted to Radix-50 notation and output to the global symbol 
directory of the object module. 

When more than one .IDENT directive is found in a given program, the 
last .IDENT found determines the symbol which is passed as part of the 
object module identification. 


5.5.1.6 Page Ejection (.PAGE Directive) - There are several means of 
obtaining a page eject in a MACRO assembly listings 

1. After a line count of 58 lines, MACRO automatically performs 
a page eject to skip over page perforations on line printer 
paper and to formulate terminal output into pages. 

2. A form feed character used as a line terminator (or as the 
only character on a line) causes a page eject. Used within a 
macro definition a form feed character causes a page eject. 
A page eject is not performed when the macro is invoked. 

3. More commonly, the .PAGE directive is used within the source 
code to perform a page eject at that point. The format of 
this directive iss 

.PAGE 

This directive takes no arguments and causes a skip to the 
top of the next page. 

Used within a macro definition, the .PAGE is ignored, but the 
page eject is performed at each invocation of that macro. 


5.5.2 Functions: .ENABL and .DSABL Directives 

Several functions are provided by MACRO through the .ENABL and .DSABL 
directives. These directives use 3-character symbolic arguments to 
designate the desired function and are of the forms: 

.ENABL arg 
.DSABL arg 

where arg is one of the legal symbolic arguments defined below. 
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The following list describes the symbolic arguments and their 
associated functions in the MACRO language: 

Symbolic 

Argument Function 


ABS 


AMA 


CDR 


FPT 


LC 


LSB 


PNC 


Enabling of this function (has no effect in 
ASEMBL) produces absolute binary output; 
(i.e., for input to the Paper Tape Software 
System absolute binary loader using a .BIN 
extension instead of .OBJ). The default case 
is .DSABL ABS. 

Enabling of this function directs the 
assembly of all relative addresses (address 
mode 67) as absolute addresses (address mode 
37). This switch is useful during the 
debugging phase of program development. 

The statement .ENABL CDR (has no effect in 
ASEMBL) causes source columns 73 and greater 
to be treated as comments. This accommodates 
sequence numbers in card columns 72-80. 

Enabling of this function (has no effect in 
ASEMBL) causes floating point truncation, 
rather than rounding as is otherwise 
performed. .DSABL FPT returns to floating 
point rounding mode. 

Enabling of this function causes the 
assembler to accept lower case ASCII input 
instead of converting it to upper case (has 
no effect in ASEMBL)• 

Enable or disable a local symbol block (has 
no effect in ASEMBL). While a local symbol 
block is normally entered by encountering a 
new symbolic label or .CSECT directive, 
.ENABL LSB forces a local symbol block which 
is not terminated until a label or .CSECT 
directive following the .DSABL LSB statement 
is encountered. The default case is .DSABL 
LSB. 

The statement .DSABL PNC (has no effect in 
ASEMBL) inhibits binary output until an 
.ENABL PNC is encountered. The default case 
is .ENABL PNC. 


An incorrect argument causes the directive containing it to be flagged 
as an error. 


5.5.3 Data Storage Directives 

A wide range of data and data types can be generated with the 
following directives and assembly characters: 
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.BYTE 

.WORD 


.ASCII 
. ASCIZ 
.RAD50 
tB 
tD 
to 

These facilities are explained in the following sections. 


5.5.3.1 .BYTE — The .BYTE directive is used to generate successive 
bytes of data. The directive is of the form: 


.BYTE exp fWHICH STORES ThE OCTAL 

/equivalent of the expression 
/EXP IN THE NEXT BYTE 

.BYTE expl,exp2,>WHICH STORES THE OCTAL 

/equivalents of THE LIST OF 
/expressions in successive BYTES, 


A legal expression must have an absolute value (or contain a reference 
to an external symbol) and must result in eight bits or less of data. 
The 16-bit value of the expression must have a high-order byte (which 
is truncated) that is either all zeros or all ones. Each operand 
expression is stored in a byte of the object program. Multiple 
operands are separated by commas and stored in successive bytes. For 
example: 

SAM»5 

.■.♦410 

.BYTE *048,SAM |060 (OCTAL EQUIVALENT OF 46 

/DECIMAL) IS STORED IN LOCATION 
1411 * 005 IS STORED IN 
/LOCATION 411 

If the high—order byte of tne expression equates to a value^other than 
0 or -1, it is truncated to the low-order eight bits and flagged with 
a T error code. If the expression is relocated)le, an A-type warning 
flag is given. 

At link time it is likely that relocation will result in an expression 
of more than eight bits, in which case, the Linker prints an error 
message. For example: 


•BYTE 23 /STORES OCTAL 23 IN NEXT BYTE 

• 8TTE 8 /RELOCATABLE VALUE CAUSES AN "A" 

/error FLAG 
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Here, X has an absolute value. 


.GLOBL X 
X «3 

• BfTE x I STORES 3 IN NEXT BYTE 

and can be linked later with another program: 

.GLOBL x 
.BYTE X 

If an operand following the .BYTE directive is null, it is interpreted 
as a zero. For example (assume assembly begins at relocatable 0): 

.■•*420 

,BTTE ,, (ZEROS ARE STORED IN BYTES 

1420. 421. AND 422, 


5.5.3.2 .WORD — The .WORD directive is used to generate successive 
words of data. The directive is of the form: 

.WORD exp I WHICH STORES THE OCTAL 

(EQUIVALENT OF THE EXRRE3S0N 
(EXP IN THE NEXT WORD 

.W0R0 expl,exp2... »WH1CM STORES THE OCTAL 

1EQUIVALENTS OF THE LIST OF 
( EXPRESSIONS IN SUCCESSIVE 
{WORDS 

where a legal expression must result in 16 bits or less of data. Each 
operand expression is stored in a word of the object program. 

Multiple operands are separated by commas and stored in successive 
words. For example: 

SAL«0 

.•.*500 

.WOR0 177535,,*4,SAL {STORES 177535, 506, AND 0 

UN WORDS 500, 502, ANO 504, 

If an expression equates to a value of more than 16 bits, it is 
truncated and flagged with a T error code. 

If an operand following the .WORD directive is null, it is interpreted 
as zero. For example: 

,••*500 

.WORD ,5, {STORES 0,5,0 IN LOCATIONS 

{500, 502, AND 504 

A blank operator field (any operator not recognized as a macro call, 
op-code, directive or semicolon) is interpreted as an implicit .WORD 
directive. Use of this convention is discouraged. The first term of 
the first expression in the operand field must not be an instruction 
mnemonic or assembler directive unless preceded by a + or — operator. 


5-39 







MACRO Assembler 


For example: 

,a,«<U0 (THE OP-CODE FOR MOV, WHICH 15 

LABEL I *M0 V,LABEL (010000, IS STORED IN LOCATION 

(440, 440 IS STOREO IN 
(LOCATION 442. 

Note that the default .WORD directive occurs whenever there is a 
leading arithmetic or logical operator, or whenever a leading symbol 
is encountered which is not recognized as a macro call, an instruction 
mnemonic or assembler directive. Therefore, if an instruction 
mnemonic, macro call, or assembler directive is misspelled, the .WORD 
directive is assumed and errors will result. Assume that MOV is 
spelled incorrectly as MOR: 

MOR A ,B 

Two error codes result: A and U. Two words are then generated, one 
for MOR A and one for B. 


5.5.3.3 ASCII Conversion of One or Two Characters - The ' and " 
characters are used to generate text characters within the source 
text. A single apostrophe followed by a character results in a term 
in which the 7-bit ASCII representation of the character is placed in 
the low-order byte and zero is placed in the high-order byte. For 
example: 


MOV #*A,R0 

results in the following 16 bits being moved into RO: 

0000000001000001 

The ' character is never followed by a carriage return, null, RUBOUT, 
line feed, or form feed. (For another use of the • character, see 
Section 5.6.3.6.) 

STMNTl 

GETSVM 
BEQ 45 

CHPB •CHRPNT,#*! 

BEQ LABEL 

CMPB 0CHRPNT'#'* 

BEQ ASGMT 


(COLON DELIMITS LABEL FIELD 

(EQUAL DELIMITS 
(ASSIGNMENT PARAMETER 


A double quote followed by two characters results in a term in which 
the 7-bit ASCII representations of the two characters are placed. For 
example: 


MOV *”AB,RB 

results in the following binary word being moved into R0: 
0100001001000001 

Note that the first character is placed in the low-order byte and the 
second character in the high-order byte. 
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The " character is never followed by a carriage return, null, rubout, 
line feed, or form feed. For example: 


/OEVICE NAME TABLE 


DEVNAMI 

.WORD 

W RF 

>RF DISK 


.WORD 

”RK 

/RK DISK 

OEVNKBI 

.WORD 

M IT 

/TERMINAL KEYBOARD 


.WORD 

»»0T 

/DECTAPE 


.WORD 

«IP 

/LINE PRINTER 


.WORD 

wpR 

/PAPER TAPE READER 


.WORD 

it pp 

/PAPER TAPE PUNCH 


.WORD 

0 

/TABLE'S END 


5.5.3.4 .ASCII - The .ASCII directive translates character strings 
into their 7-bit ASCII equivalents for use in the source program. The 
format of the .ASCII directive is: 

.ASCII /character string/ 

where: character string is a string of any acceptable printing 

ASCII characters including spaces. The 
string may not include null characters, 
rubout, return, line feed, vertical tab, 
or form feed. Nonprinting characters 
can be expressed in digits of the 
current radix and delimited by angle 
brackets. (Any legal, defined 

expression is allowed between angle 
brackets.) 

/ / are delimiting characters and may be any 

printing characters other than ; < and = 
characters and any character within the 
string. 

As an example: 

At .ASCII /HELLO/ / STORES ASCII REPRESENTATION OP 

ITHE LETTERS H E L L 0 IN 
/CONSECUTIVE BYTES 

The order of the characters as they are stored in memory is 
illustrated below. 
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.ASCII /ABC/«15»«12>/0EF/ 

I STORES 

>101,102,103,15,12,106,105,106 
>IN CONSECUTIVE BYTES 

.ASCII /«AB>/ f STOKES 76,101,102,76 IN 
^CONSECUTIVE BYTES 


The ; and — characters are not Illegal delimiting characters, but are 
preempted by their significance as a comment indicator and assignment 
operator, respectively. For other than the first group, semicolons 
are treated as beginning a comment field. For example: 



Directive 

Result 

ASCII 

;ABCj/DEF/ 

A B C D E 

ASCII 

/ABC/;DEF; 

ABC 

ASCII 

/ABC/=DEF= 

A B C D E 

ASCII 

=DEF= 



Explanation 

Acceptable, but not 

recommended procedure. 

;DEF; is treated as a comment 
and ignored. 

Acceptable, but not 

recommended procedure. 

The assignment ,ASCII=DEF is 
performed and an error 
generated upon encountering 
the second =. 


5.5.3.5 .ASCIZ - The .ASCIZ directive is equivalent to the .ASCII 
directive with a zero byte automatically inserted as the final 
character of the string. For example: 

When a list or text string has been created with a 
•ASCIZ directive, a search for the null character 
can determine the end of the list as follows: 

CR» 15 
IF»12 


MOV AHELLO,61 
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XI 






MOV #LINBUF,R2 

MOVB («!)♦»(RE)* ( MOVE A CHARACTER OF THE 

(MESSAGE STRING INTO THE 
(OUTPUT BUFFER 

BNE X (BRANCH BACK IF BYTE 

(NOT EQUAL TO 0 


HELLOl .ASCIZ «CR»«lF>/MACRO-l1 V001A/<CR>«LF> 

(INTRO MESSAGE 


5.5.3.6 .RAD50 - The .RAD50 directive allows the user the capability 
to handle symbols in Radix-50 coded form (this form is sometimes 
referred to as MOD40 and is used in PDP-11 system programs). Radix-50 
form allows three characters to be packed into sixteen bits; 
therefore, any 6-character symbol can be held in two words. The form 
of the directive is: 


.RAD50 /string/ 

where: / / delimiters can be any printing 

characters other them the =, <, and ; 
characters. 


string is a list of the characters to be 

converted (three characters per word) 
and may consist of the characters A 
through Z, 0 through 9, dollar ($), dot 
(.) and space ( ). If there are fewer 
than three characters (or if the last 
set is fewer than three characters) they 
are considered to be left justified and 
trailing spaces are assumed. Illegal 
nonprinting characters are replaced with 
a ? character and cause am I error flag 
to be set. Illegal printing characters 
set the Q error flag. 

The trailing delimiter may be a carriage return, semicolon, or 
matching delimiter. (A warning code is printed if it is not a 
matching delimiter, however.) For example: 


A 


20 

21 

00040 

003223 

,RAD50 

/ABC 

22 

00042 

003220 

•RAD50 

/AB/ 

23 

00044 

000000 

.RAD50 

// 

24 

00046 

00050 

003223 

014400 

.RAQ50 

/ ABCD/ 


(PACK ABC INTO ONE WORD 
(PACK AB (SPACE) INTO ONE WORD, 
(PACK THREE SPACES INTO ONE woro 
(PACK ABC INTO FIRST WORD AND 

ID (SPACE)(SPACE) INTO SECOND WORD 


Each character is translated into its Radix-50 
indicated: 


equivalent 


as 
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Radix-50 

Character Equivalent (octal) ASCII (octal) 


(space) 

A-Z 

$ 


0 

1-32 


40 


101-132 


33 

34 

35 


44 

56 


undefined 

0-9 


36-47 


undefined 

60-71 


Note that another character could be defined for code 35, which is 
currently unused. 

The Radix-50 equivalents for three characters (Cl,C2,C3) are combined 
in one 16-bit word as follows: 


Radix-50 value = ( (Cl*50)+C2)*50+C3 


For example: 

Radix-50 value of ABC is ((1*50)+2)*50+3 or 3223 

See Appendix E for a table to quickly determine Radix-50 equivalents. 

Use of angle brackets is encouraged in the .ASCII, .ASCIZ, and .RAD50 
statements whenever leaving the text string to insert special codes. 
For example: 


.ASCII <l0i» ^EQUIVALENT TO .ASCII/A/ 

.RAD50 /AB/«J5>I STORES 3255 IN NEXT R0RD. 

CHR1 ■l 
CHR2-2 
CHR3«i 


* 


.RAO50 <CHR1>«CHR2><CHR3» 


^EQUIVALENT TO RAD50/ABC/ 


5.5.4 Radix Control 

5.5.4.1 .RADIX 

Numbers used in a MACRO source program are initially considered to be 
octal numbers. However, the programmer has the option of declaring 
the following radices: 

2, 4, 8, 10 

This is done via the .RADIX directive of the form: 


.RADIX n 


where n is one of the acceptable radices. 
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The argument to the .RADIX directive is always interpreted in decimal 
radix. Following any radix directive, that radix is the assumed base 
for any number specified until the following .RADIX directive. 

The default radix at the start of each program, and the argument 
assumed if none is specified, is 8 (octal). For example: 

(BEGINS SECTION OF CODE WITH 
(DECIMAL RADIX 


(REVERTS TO OCTAL RAOIX 

In general it is recommended that macro definitions not contain or 
rely on radix settings from the .RADIX directive. The temporary radix 
control characters should be used within a macro definition. (tD, to, 
and tB are described in the following section.) A given radix is valid 
throughout a program until changed. Where a possible conflict exists 
within a macro definition or in possible future uses of that code 
module, it is suggested that the user specify values using the 
temporary radix controls. 


.RADIX 10 


.RADIX 


5.5.4.2 Temporary Radix Control: tD, to, and tB - Once the user has 
specified a radix for a section of code, or has determined to use the 
default octal radix, he may discover a number of cases where an 
alternate radix is more convenient (particularly within macro 
definitions). For example, the creation of a mask word might best be 
done in the binary radix. 

MACRO has three unary operators to provide a single interpretation in 
a given radix within another radix as follows: 

tDx (x is treated as being in decimal radix) 

tOx (x is treated as being in octal radix) 

tBx (x is treated as being in binary radix) 

For example: 

tD123 
to 47 

tB 00001101 
tO<A+3> 

Notice that while the uparrow and radix specification characters may 
not be separated, the radix operator can be physically separated from 
the number by spaces or tabs for formatting purposes. Where a term or 
expression is to be interpreted in another radix, it should be 
enclosed in angle brackets. 

These numeric quantities may be used any place where a numeric value 
is legal. 

A temporary radix change from octal to decimal may be made by 
specifying a decimal radix number with a "decimal point". For example: 
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100. (144(8)) 

1376. (2540(8)) 

128. (200(8)) 


5.5.5 Location Counter Control 

The four directives that control movement of the location counter are 
.EVEN and .ODD which move the counter a maximum of one byte, and .BLKB 
and .BLKW which allow the user to specify blocks of a given number of 
bytes or words to be skipped in the assembly. 


5.5.5.1 .EVEN - The .EVEN directive ensures that the assembly 
location counter contains an even memory address by adding one if the 
current address is odd. If the assembly location counter is even, no 
action is taken. Any operands following a .EVEN directive are 
ignored. 

The .EVEN directive is used as follows: 


.ASCIZ /THIS IS 4 TEST/ 
.EVEN 

.WORD XYZ 


I ASSURES NEXT STATEMENT 
IBEGINS ON A W0R0 BOUNDARY 


5.5.5.2 .ODD - The .ODD directive ensures that the assembly location 
counter is odd by adding one if it is even. For example: 


f CODE TO MOVE D*TA FROM AN INPUT CINE 
I TO A BUFFER 


N»5 


I BUFFER HAS 5 WORDS 


BUFFI 


ODD 

BYTE N*2 
BIKH N 


»C0UNT«2N BYTES 

IRESERVE BUFFER OF N WORDS 


AGAIN! 


DONE I 


LINES 


MOV SBUFF.R2 
MOV «IINE'R1 
MOVB «■!(R2).R0 
MOVB (R1) ♦»(R2) ♦ 
9EQ DONE 
DEC R0 
8NE AGAIN 


I ADDRESS OF EMPTY BUFFER IN R2 
I ADDRESS OF INPUT CINE IS IN R1 
I GET COUNT STORED IN BUFF-i IN R0 

IM0VE BYTE FROM CINE INTO BUFFER 
MAS NUCC character SEEN? 

IDECREMENT COUNT 

|NOT«0, GET NEXT CHARACTER 


CURB •(R2) I0UT OF ROOM IN BUFFER. CCEAR CAST 

I WORD 


,ASCIZ /TEXT/ 
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In this case, .ODD is used to place the buffer byte count in the byte 
preceding the buffer, as follows: 



5.5.5.3 .BLKB and .BLKW - Blocks of storage can be reserved using 
the .BLKB and .BLKW directives. .BLKB is used to reserve byte blocks 
and .BLKW reserves word blocks. The two directives are of the form: 

•BLKB exp 

.BLKW exp 

where exp is the number of bytes or words to reserve. If no argument 
is present, 1 is the assumed default value. Any legal expression 
which is completely defined at assembly time and produces an absolute 
number is legal. For example: 

1 

2 l 

3 


4 

000000 * 

.CSECT 

IMPUHE 


S 000000 

PASS! 

.BLKW 



b 




/NEXT GROUP MUST STAY TOGETHER 

7 000002 

SYMBOL! 

.BLKW 

2 

/ SYMBOL ACCUMULATOR 

9 00000b 

MODE! 




9 00000b 

FLAGS! 

.BLKB 

1 

> PLAG BITS 

10 00007 

SECTOR! 

.BLKB 

1 

> SYMBOL/EXPRESSION TYPE 

11 00010 

VALUE! 

.BLKW 

i 

/EXPRESSION VALUE 

12 00012 

KELLVL! 

.BLKW 

1 


13 


.BLKW 

2 

>END OF GROUPEO DATA 

14 00020 

CLCNAIi! 

.BLKW 

2 

/CURRENT LOCATION COUNTER 

15 00024 

CLCFGS! 

.BLKB 

1 


lb 00025 

CLCSEC! 

.BLKB 

1 


17 0002b 

CLCLOCi 

.BLKW 

i 


19 00030 

clcmaxi 

.BLKW 

1 


19 

000001 * 

.END 



The .BLKB 

directive has 

the same effect 

as: 


.=.+exp 

but is easier to interpret in the context of source code. 


5.5.6 Numeric Control 

Several directives are available to provide software complements to 
the floating-point hardware on the PDP-11. 
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A floating-point number is represented by a string of decimal digits. 
The string (which can be a single digit in length) may optionally 
contain a decimal point, and may be followed by an optional exponent 
indicator in the form of the letter E and a signed decimal exponent. 
The list of number representations below contains seven distinct, 
valid representations of the same floating-point number: 

3 

3. 

3.0 
3.0E0 
3E0 
. 3E1 
300E-2 

As can be quickly inferred, the list could be extended indefinitely 
(e.g., 3000E-3, .03E2, etc.). A leading plus sign is ignored (e.g., 

+3.0 is considered to be 3.0). Leading minus signs complement the sign 
bit. No other operators are allowed (e.g., 3.0+N is illegal). 

Floating-point number representations are valid only in the contexts 
described in the remainder of this section. 

Floating-point numbers are normally rounded. That is, when a 
floating-point number exceeds the limits of the field in which it is 
to be stored, the high-order excess bit is added to the low-order 
retained bit. For example, if the number were to be stored in a 
2-word field, but more than 32 bits were needed for its value, the 
highest bit carried out of the field would be added to the least 
significant position. In order to enable floating-point truncation, 
the .ENABL FPT directive is used and .DSABL FPT is used to return to 
floating-point rounding. 


5.5.6.1 .FLT2 and .FLT4 - Like the .WORD directive, the two 
floating-point storage directives cause their arguments to be stored 
in-line with the source program (have no effect in ASEMBL). These two 
directives are of the form: 

.FLT2 argl,arg2,... 

.FLT4 argl,arg2,... 

where argl,arg2, etc. represent one or more floating point numbers 
separated by commas. 

.FLT2 causes two words of storage to be generated for each argument 
while .FLT4 generates four words of storage. 
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The following code shows the use of the .FLT4 directive: 


2 

3 


4 

00000(9 

037314 AT0FT6I 

.FLT4 

1 »E«*1 


000002 

146314 




000004 

146314 




00000b 

146315 



5 

000010 

036443 

,FLT4 

l.E-2 


000012 

153412 




000014 

036560 




000016 

121727 



6 

000020 

034721 

,FLT4 

l «E»4 


000022 

133427 




000024 

054342 




000026 

014545 



7 

000030 

031453 

.FLT4 

i.E-e 


000032 

146167 




000034 

010604 




000036 

060717 



6 

000040 

022746 

.FLT4 

l.E-16 


000040 

112624 




000044 

137304 




000046 

046741 



9 

000050 

005517 

,FLT4 

1 .E-32 


000052 

130436 




000054 

126505 




000056 

034625 




1 10**1 

110**2 

110**4 

110**6 

110**16 

I 10**32 

tF and tC - Like the temporary 


5.5.6.2 Temporary Numeric Control 
radix control operators, operators are available to specify either a 
1-word floating-point number (tF—not available in ASEMBL) or the 
one*s complement of a 1-word number (tC). For example: 


FL3.7: tF3.7 

creates a 1-word floating-point number at location FL3.7 containing 
the value 3.7 as follows: 


SIGN 

BIT 


15 14 


7 6 


0 


S 


EXPONENT 


MANTISSA 


This 1-word floating-point number is the first word of the 2- or 

4-word floating-point number format shown in the PDP-11 Processor 
Handbook , and the statement: 

CMP151: tCl51 

stores the one's complement of 151 in the current radix (assume 
current radix is octal) as follows: 
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177626 


Since these control operators are unary operators f their arguments may 
be integer constants or symbols, and the operators may be expressed 
successively. For examples 


tCtD25 or tC31 or 177746 


The term created by the unary operator and its argument is then a term 
which can be used by itself or in an expression. For examples 


tC2+6 


is equivalent tos 


< tC2 >+6 or 177775+6 or 000003 


For this reason, the use of angle brackets is advised. Expressions 
used as terms or arguments of a unary operator must be explicitly 
grouped. 


An example of the importance 
operators is shown belows 


of ordering with respect 


to unary 


tFl.O = 040200 

tF-1.0 = 140200 

-tFl.O = 137600 

-tF-1.0 = 037600 


The argument to the tF operator must not be an expression and should 
be of the same format as arguments to the .FLT2 and .FLT4 directives. 


5.5.7 Terminating Directives 


5.5.7.1 .END - The .END directive indicates the physical end of the 
source program. The .END directive is of the form: 

•END exp 


where exp is an optional argument which, if present, indicates 
program entry point, i.e., the transfer address. 


the 
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When the load module is loaded, program execution begins at the 
transfer address indicated by the .END directive. In a runtime system 
(the load module output of the Linker) a .END exp statement should 
terminate the first object module and .END statements should terminate 
any other object modules. 


5.5.7.2 .EOT - Under the RT-11 System, the .EOT directive is 
ignored. The physical end file allows several physically separate 
tapes to be assembled as one program. 


5.5.8 Program Boundaries Directive: .LIMIT 

The .LIMIT directive reserves two words into which the Linker puts the 
low and high addresses of the load module's relocatable code (the load 
module is the result of the link). The low address (inserted into the 
first word) is the address of the first byte of code. The high 
address is the address of the first free byte following the relocated 
code. These addresses are always even since all relocatable sections 
are loaded at even addresses. (If a relocatable section consists of 
an odd number of bytes, the Linker adds one to the size to make it 
even.) 


5.5.9 Program Section Directives 

The assembler provides for 255(10) program sections: an absolute 
section declared by .ASECT, an unnamed relocatable program section 
declared by .CSECT, and 253(10) named relocatable program sections 
declared by .CSECT symbol, where symbol is any legal symbolic name. 
These directives allow the user to: 

1. Create his program (object module) in sections: 

The assembler maintains separate location counters for each 
section. This allows the user to write statements which are 
not physically contiguous but will be loaded contiguously. 
The following examples will clarify this: 
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A I 
01 
Cl 

sn 


.csect Istart the unnamed relocatable section 

Z (ASSEMBLED at RELOCATABLE 0» 

z irelocatable 2 and 

z {RELOCATABLE 4 

CLR A {ASSEMBLE COOE AT 

CLR B (RELOCATABLE ADDRESS 

CLR C (S THROUGH 21 

.ASECT (START THE ABSOLUTE SECTION 

,«4 (ASSEMBLE CODE AT 

.WORD ,*2,HALT (ABSOLUTE 4 THROUGH 7 

.CSECT (RESUME THE UNNAMED RELOCATABLE 

(SECTION 

INC A (ASSEMBLE CODE AT 

BR ST (RELOCATABLE 22 THROUGH 27 

.END 


The first appearance of .CSECT or .ASECT assumes the location 
counter is at relocatable or absolute zero, respectively. 
The scope of each directive extends until a directive to the 
contrary is given. Further occurrences of the same .CSECT or 
.ASECT resume assembling where the section was left off. 



•CSECT 

C0M1 

(OECLARE SECTION C0M1 


A t 

0 


(ASSEMBLED AT RELOCATABLE 

0 

B 1 

0 


(ASSEMBLED AT RELOCATABLE 

I 

Cl 

0 

•CSECT 

COM2 

(ASSEMBLED AT RELOCATABLE 
(DECLARE SECTION COM2 

a 

XI 

0 


(A.SSEMBLEO AT RELOCATABLE 

0 

Yl 

0 

•CSECT 

C0M1 

(ASSEMBLED AT RELOCATABLE 
(RETURN TO COM! 

2 

01 

0 

• END 


(ASSEMBLED AT RELOCATABLE 

b 


The assembler automatically begins assembling at relocatable 
zero of the unnamed .CSECT if not instructed otherwise; that 
is, the first statement of an assembly is an implied .CSECT. 

All labels in an absolute section are absolute; all labels 
in a relocatable section are relocatable. The location 
counter symbol, is relocated) le or absolute when 
referenced in a relocatable or absolute section, 
respectively. Undefined internal symbols are assigned the 
value of relocatable or absolute zero in a relocatable or 
absolute section, respectively. Any labels appearing on a 
.ASECT or .CSECT statement are assigned the value of the 
location counter before the .ASECT or .CSECT takes effect. 
Thus, if the first statement of a program is: 

Al .ASECT 

then A is assigned to relocatable zero and is associated with 
the unnamed relocatable section (because the assembler 
implicitly begins assembly in the unnamed relocatable 
section). 

Since it is not known at assembly time where the program 
sections are to be loaded, all references between sections in 
a single assembly are translated by the assembler to 
references relative to the base of that section. The 
assembler provides the Linker with the necessary information 
to resolve the linkage. Note that this is not necessary when 
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making a reference to an absolute section (the 
knows all load addresses of an absolute section). 

Examples: 


assembler 


AS 


•ASECT 

•*1000 

CL* X 
JMP Y 


I ASSEMBLED AS CLR BASE OF UNNAMED 
^RELOCATABLE SECTION +12 
ASSEMBLED AS JMP BASE OF UNNAMED 
IRELOCATABLE SECTION ♦ 10 


Y I 
XI 


•CSECT 
MOV R0,R1 
JMP A 
HALT 
0 

• end 


I ASSEMBLED AS JMP 1000 


In the above example the references to X and Y were 
translated into references relative to the base of the 
unnamed relocatable section. 

2. Share code and/or data between object modules (separate 
assemblies): 

Named relocatable program sections operate as FORTRAN labeled 
COMMON; that is, sections of the same name from different 
assemblies are all loaded at the same location by LINK. The 
unnamed relocatable section is the exception to this as all 
unnamed relocatable sections are loaded in unique areas by 
LINK. 

Note that there is no conflict between internal symbolic 
names and program section names; that is, it is legal to use 
the same symbolic name for both purposes. In fact, 
considering FORTRAN again, this is necessary to accommodate 
the FORTRAN statement: 


COMMON 


/X/A,B,C,X 


where the symbol X represents the base of this program 
section and also the fourth element of this program section. 

Program section names should not duplicate .GLOBL names. In 
FORTRAN language, COMMON block names and SUBROUTINE names 
should not be the same. 


The .ASECT and .CSECT program section directives are provided in MACRO 
to allow the user to specify an unnamed absolute or relocatable 
section. These directives are formatted as follows: 

.ASECT 

.CSECT 

.CSECT symbol 
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The single absolute section can be declared with an: 

.ASECT 

directive. No name can be associated with the absolute section 
specified by means of the .ASECT directive. The single unnamed 
relocatable program section can be declared with a: 

.CSECT 


directive. 

All named relocatable sections are loaded in unique areas by LINK. Up 
to 253(10) named relocatable program sections can be declared with: 

.CSECT symbol 

directives, where symbol is any legal symbolic name. 

The assembler automatically begins assembling at relocatable zero of 
the unnamed .CSECT if not instructed otherwise; that is, the first 
statement of an assembly is an implied .CSECT. 


5.5.10 Symbol Control: .GLOBL 

If a program is created in segments which are assembled separately, 
global symbols are used to allow reference to one symbol by the 
different segments. 

A global symbol must be declared in a .GLOBL directive. The form of 
the .GLOBL directive is: 

.GLOBL syml,sym2,... 

where: 

syml,sym2, etc. are legal symbolic names, separated by 

commas, tabs, or spaces where more them 
one symbol is specified. 

Symbols appearing in a .GLOBL directive are either defined within the 
current program or are external symbols, in which case they are 
defined in another program which is to be linked with the current 
program, by LINK, prior to execution. 

A .GLOBL directive line may contain a label in the label field and 
comments in the comment field. 


>0EMNE * SUBROUTINE WITH 2 ENTRY POINTS WHICH 
ICALLS AN EXTERNAL SUBROUTINE 


.CSECT IDECLARE THE CONTROL SECTION 

.GLOBL A,B,C DECLARE A,B,C A8 GLOBALS 

MOV B(R5)*,R0 »ENTRY A IS DEFINED 

MOV # X,R1 

PC,C I CALL EXTERNAL SUBROUTINE C 
*TS R5 >EXIT 

MOV »CR5)*,Ri I0EFINE ENTRY B 

CLR RI 

BR X 


January 1976 
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In the previous example, A and B are entry symbols (entry 
is an external symbol and X is an internal symbol. 


points), 


C 


A global symbol is defined only when it appears in a .GLOBL directive. 
A symbol is not considered a global symbol if it is assigned the value 
o a global expression m a direct assignment statement. 


References 
instruction 
i.e.: 


to external symbols can appear in the operand field of an 
or assembler directive in the form of a direct reference. 


CLR EXT 

.WORD EXT 

CLR #EXT 

or a direct reference plus or minus a constant, i.e.: 

0«b 

CLR EXT^D 

•WORD EXT-2 

CLR #EXT*0 

A global symbol defined within the program can be used in the evalua¬ 
tion of a direct assignment statement, but an external symbol cannot. 
Since MACRO determines at the end of pass 1 whether a given global sym¬ 
bol is defined within the program or is expected to be external, a con¬ 
struction such as the following will cause errors at link time: 

.GLOBL FREE 
.GLOBL LIMITS 

FREE-LIMITS + 2 ? FREE WILL NOT BE 

;DEFINED UNTIL PASS 2 


LIMITS: .LIMIT 


FREE will be flagged as an undefined global at link time. To allow 
correct linking, define FREE after LIMITS:. 


5.5.11 Conditional Assembly Directives 

Conditional assembly directives provide the programmer with the 
capability to conditionally include or ignore blocks of source code in 
the assembly process. This technique is used extensively to allow 
several variations of a program to be generated from the source 
program. 

The general form of a conditional block is as follows: 

.IF cond,argument(s) ;START CONDITIONAL BLOCK 

• ;STATEMENTS IN RANGE OF 

. ;CONDITIONAL 

. ;BLOCK 

•ENDC ;END CONDITIONAL BLOCK 

where: cond is a condition which must be met if the block is 

to be included in the assembly. These conditions 
are defined below. 
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argument(s) are a function of the condition to be tested. If 
more than one argument is specified, they must be 
separated by commas. 

range is the body of code which is included in the 

assembly or ignored depending upon whether the 
condition is met. 


The following 

are the 

allowable conditions: 


Conditions 

Positive Complement 

Arguments 

Assemble Block If 

EQ 

NE 

expression 

expressions (or 7 * 0) 

GT 

LE 

expression 

expressionX) (or £ 0) 

LT 

GE 

expression 

expressions (or >_0) 

DF 

NDF 

symbolic 

argument 

symbol is defined 
(or undefined) 

B 

NB 

macro-type 
argument 

argument is blank 
(or nonblank) 

IDN 

DIF 

two macro-type 
arguments separated 
by a comma 

arguments identical 
(or different) 

Z 

NZ 

expression 

same as EQ/NE 

G 


expression 

same as GT/LE 

L 


expression 

same as LT/GE 

IF DIF and IF 

IDN are 

not available in ASEf4BL # 



NOTE 

A macro-type argument is enclosed in 
angle brackets or within an up-arrow 
construction (as described in Section 
5.2.1.1). For example: 

<A,B,C> 

t/124/ 

For example: 

ALPHA*-) 

.IF EQ» ALPHA*) )ASSEMBLE IF ALPHA*)*® 

• ENDC 

Within the conditions DF and NDF the following two operators are 
allowed to group symbolic arguments: 

& logical AND operator 

1 logical inclusive OR operator 
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For example: 

.IF DF.SYMi l SYH2 I ASSEMBLE IF BOTH SYMJ 
• IANO SYM2 ARE DEFINED 

• ENDC 


5.5.11.1 Subconditionals - Subconditionals may be placed within 
conditional blocks to indicate: 

1. assembly of an alternate body of code when the condition of 
the block indicates that the code within the block is not to 
be assembled, 

2. assembly of a non-contiguous body of code within the 

conditional block depending upon the result of the 

conditional test to enter the block, 

3. unconditional assembly of a body of code within a conditional 
block. 

There are three subconditional directives, as follows: 

Su bconditional Function 

.IFF The code following this statement up to the next 

subconditional or end of the conditional block is 
included in the program if the value of the 

condition tested upon entering the conditional 
block is false. 

•IFT The code following this statement up to the next 

subconditional or end of the conditional block is 
included in the program if the value of the 

condition tested upon entering the conditional 
block is true. 

.IFTF The code following this statement up to the next 

subconditional or the end of the conditional block 
is included in the program regardless of the value 
of the condition tested upon entering the 
conditional block. 

The implied argument of the subconditionals is the value of the 

condition upon entering the conditional block. Subconditionals are 
used within outer level conditional blocks. Subconditionals are 
ignored within nested, unsatisfied conditional blocks. 

For example: 
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( ASSEMBLE BLOCK IF SYM IS DEFINED 
(ASSEMBLE THE FOLLOWING CODE ONLY IF 
(SYM IS UNDEFINED 


.IF OF,SYM 

.IFF 


• IFT 

. IFTF 

,ENDC 


(ASSEMBLE THE FOLLOWING CODE ONLY IF 
(SYM IS OEFINED 


(ASSEMBLE THE FOLLOWING CODE 
(UNCONDITIONALLY 


•IF OF,X 
.IF OF, Y 
.IFF 




.IFT 

B 

,ENDC 
, ENDC 


(ASSEMBLY TESTS FALSE 

(TESTS FALSE 

(NESTED CONDITIONAL 

(IGNORED WITHIN NESTED. UNSATISFIED 

(CONDITIONAL BLOCK 


(NOT SEEN 



However, 


.IF DFiX 
.IF DF, Y 
.IFF 


(TESTS TRUE 
(TESTS FALSE 
(IS ASSEMBLED 

(OUTER CONDITIONAL SATISFIED. 


.IFT (NOT ASSEMBLED 


.ENDC 

.ENDC 


5.5.11.2 Immediate Conditionals - An immediate conditional directive 
is a means of writing a 1-line conditional block. In this form, no 
.ENDC statement is required and the condition is completely expressed 
on the line containing the conditional directive. Immediate 
conditions are of the form: 


where: 


.IIF cond, arg, statement 


cond 


is one of the legal conditions defined 
conditional blocks in Section 5.5.11. 


for 
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arg is the argument associated with the conditional 

specified, that is, either an expression, symbol, 
or macro-type argument, as described in Section 
5.5.11. 

statement is the statement to be executed if the condition 
is met. 


For example: 


.IIF DF,F00,BEQ ALPHA 

This statement generates the code: 

BIO ALPHA 

if the symbol FOO is defined. 

A label must not be placed in the label field of the .IIF statement. 
Any necessary labels may be placed on the previous line, as in the 
following example: 

LABEL l 

.IIF OF,FPP BEQ ALPHA 

or included as part of the conditional statement: 

.IIF OF ,F 00 LABEL I BEO ALPHA 


5.5.11.3 PAL-llR and PAL-11S Conditional Assembly Directives - In 
order to maintain compatibility with programs developed under PAL-llR 
and PAL-11S, the following conditionals remain permissible under 
MACRO. It is advisable that future programs be developed using the 
format for MACRO conditional assembly directives. 


Directive 


Arguments 


Assemble Block if 


•IFZ or .IFEQ 
.IFNZ or.IFNE 
.IFL or .IFLT 
.IFG or .IFGT 
.IFGE 
. IFLE 
.IFDF 
.IFNDF 


expression 
expression 
expression 
expression 
expression 
expression 
logical expression 
logical expression 


expressions 
expression^ 
expression<0 
expression>0 
expression=>0 
expression<=0 

expression is true(defined) 
expression is false(undefined) 


The rules governing the usage of these directives are now the same as 
for the MACRO conditional assembly directives previously described. 
Conditional assembly blocks must end with the .ENDC directive and are 
limited to a nesting depth of 16(10) levels (instead of the 127(10) 
levels allowed under PAL-llR). 
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5.6 MACRO DIRECTIVES 


5.6.1 Macro Definition 

It is often convenient in assembly language programming to generate a 
recurring coding sequence with a single statement. In order to do 
this, the desired coding sequence is first defined with dummy 
arguments as a macro. Once a macro has been defined, a single 
statement calling the macro by name with a list of real arguments 
(replacing the corresponding dummy arguments in the definition) 
generates the correct sequence or expansion. 


5.6.1.1 .MACRO - The first statement of a macro definition must be a 

.MACRO directive (not available in ASEMBL). The .MACRO directive is of 
the form: 

.MACRO name, dummy argument list 

where: 


name is the name of the macro. This name is any legal 

symbol. The name chosen may be used as a label 
elsewhere in the program. 

represents any legal separator (generally a comma 
or space). 


dummy 

argument 

list 


zero, one, or more legal symbols which may appear 
anywhere in the body of the macro definition, 
even as a label. These symbols can be used 
elsewhere in the user program with no conflicts of 
definition. Where more than one dummy argument is 
used, they are separated by any legal separator 
(generally a comma)• 


A comment may follow the dummy argument list in a statement containing 
a .MACRO directive. For example: 

• MAC HQ ABS A,B I DEFINE MACRO ABS WITH TWO ARGUMENTS 


A label must not appear on a .MACRO statement. Labels are sometimes 
used on macro calls, but serve no function when attached to .MACRO 
statements. 


5.6.1.2 .ENDM - The final statement of every macro definition must 
be an .ENDM directive (not available in ASEMBL) of the form: 

.ENDM name 

where name is an optional argument and is the name of the macro being 
terminated by the statement. 

For example: 
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.ENDM (terminates the current macro definition) 

.ENDM ABS (terminates the definition of the macro ABS) 

If specified, the symbolic name in the .ENDM statement must correspond 
to that in the matching .MACRO statement. Otherwise the statement is 
flagged and processing continues. Specification of the macro name in 
the .ENDM statement permits the assembler to detect missing .ENDM 
statements or improperly nested macro definitions. 

The .ENDM statement may contain a comment field, but must not contain 
a label. 

An example of a macro definition is shown below: 

.MACRO TYPMSC MESSGE ITVRE A MESSAGE 
JSR R5* T YPMSG 

.WORD MESSGE 
.ENDM 


5.6.1.3 .MEXIT — In order to implement alternate exit points from a 
macro (particularly nested macros), the .MEXIT directive is provided. 
.MEXIT (not available in ASEMBL) terminates the current macro as 
though an .ENDM directive were encountered. Use of .MEXIT bypasses 
the complications of conditional nesting and alternate paths. For 
example: 


MACRO 

• 

ALTR 

N» A, B 

» 

IF 

• 

E0,N 

> START CONDITIONAL BLOCK 

« 

MEXIT 


IEXIT FROM MACRO DURING CONDITIONAL 
1 BLOCK 

ENOC 

• 


1 END CONDITIONAL BLOCK 

• 

ENOM 


JNORMAL END OF MACRO 


In an assembly where N=0, the .MEXIT directive terminates the macro 
expansion. 

Where macros are nested, a .MEXIT causes an exit to the next higher 
level. A .MEXIT encountered outside a macro definition is flagged as 
an error. 


5.6.1.4 Macro Definition Formatting — A form feed character used as 
a line terminator in a macro source statement (or as the only 
character on a line), causes a page eject when the source program is 
listed. Used within a macro definition, a form feed character also 
causes a page eject. A page eject is not performed, however, when the 
macro is invoked. 


5-61 







MACRO Assembler 


Used within a macro definition, the .PAGE directive is ignored, but a 
page eject is performed at invocation of that macro. 


5.6.2 Macro Calls 

A macro must be defined prior to its first reference. Macro calls are 
of the general forms 

labels name, real arguments 

wheres label represents an optional statement label. 

name represents the name of the macro specified in the 

.MACRO directive preceding the macro definition. 

, represents any legal separator (comma, space, or 

ted)). No separator is necessary where there are no 
real arguments. (Refer to Section 5.2.1.1.) 


real arguments 

are those symbols, expressions, and values which 
replace the dummy arguments in the .MACRO 
statement. Where more than one argument is used, 
they are separated by any legal separator. 

Where a macro name is the same as a user label, the appearance of the 
symbol in the operation field designates a macro call, and the 
occurrence of the symbol in the operand field designates a label 
reference. For example: 


NOV 

• 

•R0,R1 

/ABS IS 

USED AS A LABEL 

• 

Bfl 

• 

ABS 

/ABS IS 

CONSIDERED A LABEL 

• 

ABS 

#«,ENT,LAR 

/CALL MACRO WITH 3 ARGUMENTS 


Arguments to the macro call are treated as character strings whose 
usage is determined by the macro definition. 


5.6.3 Arguments to Macro Calls and Definitions 

Arguments within a macro definition or macro call are separated from 
other arguments by any of the separating characters described in 
Section 5.2.1.1. For example: 

.MACRO REN A,B|C /MACRO DEFINITION 

REN ALPHA,BETA,«Ci,C2> /MACRO CALL 


5-62 





MACRO Assembler 


Arguments which contain separating characters 
angle brackets. An up-arrow construction is 
brackets to be passed as arguments. 


are enclosed in paired 
provided to allow angle 


For example: 


REN «MQV X,y»,#««,WEV 


This call would cause the entire statement: 

MOV X,Y 

to replace all occurrences of the symbol A in the macro definition. 
Real arguments within a macro call are considered to be character 
strings and are treated as a single entity until their use in the 
macro expansion. 

The up—arrow construction could have been used in the above macro call 
as follows: 


REN -/MOV X, V/,#4«,WCV 

which is equivalent to: 

REN «<M0V X, Y>,#<u,WEV 

Since spaces are ignored preceding an argument, they can be used to 
increase legibility of bracketed constructions. 


5.6.3.1 Macro Nesting - Macro nesting (nested macro calls), where the 
expansion of one macro includes a call to another macro, causes one 
set of angle brackets to be removed from an argument with each nesting 
level. The depth of nesting allowed is dependent upon the amount of 
memory space used by the program. To pass an argument containing 
legal argument delimiters to nested macros, the argument should be 
enclosed in one set of angle brackets for each level of nestinq. as 
shown below: 


R0»X0 

R1*X1 

X*i0 

.macro 

LtVELl DUM1,DUM* 


levels 

DUM1 


levels 

DUM* 


.ENOM 

.MACRO 

LEVELS DUM3 


DUM3 

ADO 

#10,R0 


MOV 

R0,(R1) ♦ 


.ENOM 

A call to the LEVELl macro: 

LEVEL1 ««M0V X,R0>»,««CLR R0>> 

causes the following expansion: 
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MOV 

X, R0 

ADD 

#10*R0 

MOV 

R0>(Rl)+ 

CIR 

R0 

AOD 

•10»R0 

MOV 

R0»(Rl) ♦ 


Where macro definitions are nested (that is, a macro definition is 
entirely contained within the definition of another macro) the inner 
definition is not defined as a callable macro until the outer macro 
has been called and expanded. For examples 

.MACRO LV1 
.MACRO LV2 A 

,EWM 
• ENDM 


The LV2 macro cannot be called by name until after the first call to 
the LV1 macro. Likewise , any macro defined within the LV2 macro 
definition cannot be referenced directly until LV2 has been called. 


5»6.3.2 Special Characters - Arguments may include special characters 
without enclosing the argument in a bracket construction if that 
argument does not contain spaces, tabs, semicolons, or commas. For 
examples 

.macro push arg 

MOV ARG,-C$P) 

.ENOM 

PUSH X+3CX2) 
generates the following codes 

MOV X*3(X2) 


5.6.3.3 Numeric Arguments Passed as Symbols - When passing macro 
arguments, a useful capability is to pass a symbol which can be 
treated by the macro as a numeric string. An argument preceded by the 
unary operator backslash (\) is treated as a number in the current 
radix. (\ is not available in ASEMBL.) The ASCII characters 
representing the number are inserted in the macro expansionf their 
function is defined in context (see Section 5.6.3.6 for an explanation 
of single-quote usage). For example: 


5-64 








MACRO Assembler 


.MACRO CNT A,6 

A'8l ,WORD 
.ENDM 
C«0 

.MACRO INC A f B 

CNT A|VB 

6«Bt 1 
.ENDM 


INC X,C 


The macro call would expand to: 

X0t .WORD 

A subsequent identical call to the same macro would generate: 
X1S .WORD 


and so on for later calls. The two macros are necessary because the 
dummy value of B cannot be updated in the CNT macro. In the CNT 
macro , the number passed is treated as a string argument. (Where the 
value of the real argument is 0, a single 0 character is passed to the 
macro expansion.) 


The number being passed can also 
somewhat clearer. For example 
conditional assembly of a single 
follows: 


.MACRO 

I0T 

SYM 

. I0ENT 

/SYM/ 


.endm 

I0T 


.MACRO 

OUT 

ARG 

I0T 

005A»ARG 



.end* 

OUT \ID 

The above macro call expands tos 


be used to make source listings 
versions of programs created through 
source can identify themselves as 

I ASSUME THAT THE SYMBOL ID TAKES 
ION A UNIQUE 2 DISIT VALUE FOR 
IEACH POSSIBLE CONDITIONAL 
I ASSEMBLY OF THE PROGRAM 


INHERE 005A IS THE UPOATE VERSION 
I OF THE PROGRAM AND ARG INDICATES 
ITHE CONDITIONAL ASSEMBLY VERSION 


.IDENT /005AXX/ 

where XX is the conditional value of ID. 

Two macros are necessary since the text delimiting characters in the 
.IDENT statement would inhibit the concatenation of a dummy argument. 
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5.6.3.4 Number of Arguments - If more arguments appear in the macro 
call than in the macro definition, the excess arguments are ignored. 
If fewer arguments appear in the macro call than in the definition, 
missing arguments are assumed to be null (consist of no characters)• 
The conditional directives .IF B and .IF NB can be used within the 
macro to detect null arguments. 

A macro can be defined with no arguments. 


5.6.3.5 Automatically Created Symbols Within User-Defined Macros - 
MACRO can be made to create symbols of the form n$ where n is a 
decimal integer number such that 64<=n<=127. Created symbols are al¬ 
ways local symbols between 64$ and 127$. Such local symbols are crea¬ 
ted by the assembler in numerical order, i.e.: 

64$ 

65$ 


126$ 

127$ 


Created symbols are particularly useful where a label is required in 
the expanded macro. Such a label must otherwise be explicitly stated 
as an argument with each macro call or the same label is generated 
with each expansion (resulting in a multiply-defined label). Unless a 
label is referenced from outside the macro, there is no reason for the 
programmer to be concerned with that label. 

The range of these local symbols extends between two explicit labels. 
Each new explicit label causes a new local symbol block to be 
initialized. 

The macro processor creates a local symbol on each call of a macro 
whose definition contains a dummy argument preceded by the ? 
character. For example: 


.MACRO 

ALPHA 

TST 

A 

BEQ 

ft 

ADD 

#5, A 


8 l 

• Endm 


Local symbols are generated only where the real argument of the macro 
call is either null or missing. If a real argument is specified in 
the macro call, the generation of a local symbol is inhibited and 
normal replacement is performed. Consider the following expansions of 
the macro ALPHA above. 
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Generate a local symbol for missing argument: 

ALPHA XI 

T5T Xi 

BCD 64S 

ADD *5? XI 


Do not generate a local symbol: 

ALPHA X2.XYZ 

TST Xi 

BED XYZ 

ADD #5, Xi 


These assembler-generated symbols are restricted to the first sixteen 
(decimal) arguments of a macro definition. 


5.6.3.6 Concatenation - The apostrophe or single quote character (') 
operates as a legal separating character in macro definitions. An • 
character which precedes and/or follows a dummy argument in a macro 
definition is removed, and the substitution of the real argument 
occurs at that point. For example: 

.MACRO DEF A,0,c 

A'B: .ASCIZ /C/ 

. WORO "A"»B 
, ENDM 

When this macro is called: 

DEF X, Y,<MACR0-il> 

it expands as follows: * 

XYl .ASCIZ /MACRO-11/ 

.WORD 'X * Y 

In the macro definition, the scan terminates upon finding the first ' 
character. Since A is a dummy argument, the ' is removed. The scan 
resumes with B, notes B as another dummy argument and concatenates the 
two dummy arguments. The third dummy argument is noted as going into 
the operand of the .ASCIZ directive. On the next line (this example 
is for purely illustrative purposes) the argument to .WORD is seen as 
follows: The scan begins with a ' character. Since it is neither 
preceded nor followed by a dummy argument, the • character remains in 
the macro definition. The scan then encounters the second • character 
which is followed by a dummy argument and is discarded. The scam of 
the argument A terminates upon encountering the second ' which is also 
discarded since it follows a dummy argument. The next ' character is 
neither preceded nor followed by a dummy argument and remains in the 
macro expansion. The last * character is followed by another dummy 
argument and is discarded. (Note that the five ' characters were 
necessary to generate two * characters in the macro expansion.) 

Within nested macro definitions, multiple single quotes can be used, 
with one quote removed at each level of macro nesting. 
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5.6.4 .NARG, .NCHR, and .NTYPE 

These three directives allow the user to obtain the number of 
arguments in a macro call (.NARG), the number of characters in an 
argument (.NCHR), or the addressing mode of an argument (.NTYPE). 
(They are not available in ASEMBL.) Use of these directives permits 
selective modifications of a macro depending upon the nature of the 
arguments passed. 

The .NARG directive enables the macro being expanded to determine the 
number of arguments supplied in the macro call and is of the form; 

label: .NARG symbol 

where: label is an optional statement label 

symbol is any legal symbol which is equated to the number 
of arguments in the macro call currently being 
expanded. The symbol can be used by itself or in 
expressions. 

This directive can occur only within a macro definition. An example 


of the use of .NARG follows. 

.MACRO 

ARGS 

A 1,A2 » A3» Afl 

.NARG 

NUM 


.if eo 

NUM* 1 

1 IF A 2, A3, A H WERE 
> NOT SPECIFIED 

.WORD 

A 1 


.IFF 

.WORD 

A 1 

IIF ALL ARGS WERE GIVEN 

.ASCII 

/ A 2 / 


.WORD 

A3 


.ASCII 

.ENDC 

,£NDM 

/ A 4 / 


ARGS 

.WORD 

ALPHA 

ALPHA 

generated 

ARGS 

ALPHA.BETA,GAMMA,DECTA 

.WORD 

.ASCII 

ALPHA 

/BETA/ 

generated 

.WORD 

GAMMA 


.ASCII 

/DELTA/ 



The .NCHR directive enables a program to determine the number of 
characters in a character string, and is of the form: 


where: 


label: .NCHR symbol, <character string> 

label is an optional statement label 

symbol is any legal symbol which is equated to the number 
of characters in the specified character string. 
The symbol is separated from the character string 
argument by any legal separator. 


# 
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<character string> 

is a string of printing characters which should 
only be enclosed in angle brackets if it contains 
a legal separator, A semicolon also terminates 
the character string. 

This directive can occur anywhere in a MACRO program. For example: 


MACRO 

CHARS A 



NCHR 

NUM, A 



ASCII 

/A/ 



IF EQ 

NUM&l 

I IF 

THE STRING CONTAINS 



IAN 

EVEN NUMBER OF 



fCHARACTERS 

WORO 

•1 



IFF 


»IF 

string length is 000 

BYTE 

*2 



ENDC 




ENOM 





For example, using the above definition the code: 

CHARS ALPHA 

expands to: 

.ASCII /ALPHA/ 

.BYTE -2 

and 


CHARS BETA 

expands to: 

.ASCII /BETA/ 

.WORD -1 

The .NTYPE directive enables the macro being expanded to determine the 
addressing mode and register of any argument, and is of the form: 


where: 


label: .NTYPE symbol, arg 

label is an optional statement label 

symbol is any legal symbol, the low order 6-bits of which 

is equated to the 6-bit addressing mode of the 
argument. The symbol is separated from the 
argument by a legal separator. This symbol can be 
used by itself or in expressions. 

arg is any legal macro argument (dummy argument) as 

defined in Section 5.6.3, 


This directive can occur only within a macro definition 
of .NTYPE usage in a macro definition is shown below: 


An example 
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.MACRO SAVE ARG 
,NT YPE SYM,ARG 
.IF EU# 5YMA70 

MOV ARGiTEMP 

• IFF 

MOV #ARGr TEMP 

.ENDC 

.ENDM 


^REGISTER MODE 

inon-register MODE 


Using this definition, the code: 

SAVE R2 

expands to: 

MOV #R2iTEMP 

and 

SAVE ALPHA 

expands to: 

MOV #ALPHAiTEMP 


S 


5.6.5 .ERROR and .PRINT 


The .ERROR directive (not available in ASEMBL) is used to output 
messages to the listing file during assembly pass 2. A common use is 
to provide diagnostic announcements of a rejected or erroneous macro 
call. The form of the .ERROR directive is as follows: 

label: .ERROR expr;text 


where: label is an optional statement label 


expr is an optional legal expression whose value is 

output to the listing file when the .ERROR 
directive is encountered. Where expr is not 

specified, the text only is output to the listing 
file. 

; denotes the beginning of the text string to be 

output. 

text is the string to be output to the listing file. 

The text string is terminated by a line 

terminator. 


Upon encountering a .ERROR directive anywhere in a MACRO program, the 
assembler outputs a single line containing: 

1. the sequence number of the .ERROR directive line, 

2. the current value of the location counter, 

3. the value of the expression if one is specified, and. 
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4. the text string specified. 

For example, assume the following error macro occurs: 

.MACRO STORE SRC <OEST 
,NT Y RE A.OEST 

.IF EQ»<A&7>»6 11F STACK POINTER USED 

.ERROR AjUNACCEPTABLE MACRO ARGUMENT 

.IFF 

MOV SRC»0EST 

. ENOC 

.fcNQM 


STORE R3» (SP) 


and the following line is output: 

****** P 

00000 000076 .ERROR A,UNACCEPTABLE MACRO ARGUMENT 

This message is used to indicate an inability of the subject macro to 
cope with the argument DEST which is detected as being indexed 
deferred addressing mode (mode 70) with the stack pointer (%6) used as 
the index register. The line is flagged on the assembly listing with 
a P error code. 

The .PRINT directive is identical to .ERROR except that it is not 
flagged with a P error code. (.PRINT is not available in ASEMBL.) 


5.6.6 Indefinite Repeat Block: .IRP and .IRPC 

An indefinite repeat block (not available in ASEMBL) is a structure 
very similar to a macro definition. An indefinite repeat is 
essentially a macro definition which has only one dummy argument and 
is expanded once for every real argument supplied. An indefinite 
repeat block is coded in-line with its expansion rather than being 
referenced by name as a macro is referenced. An indefinite repeat 
block is of the form: 


label: 


.IRP arg,<real arguments> 


(range of the indefinite repeat) 


.ENDM 

where: label is an optional statement label, A label may not 

appear on any ,IRP statement within another macro 
definition, repeat range or indefinite repeat 
range, or on any .ENDM statement, 

arg is a dummy argument which is successively replaced 

with the real arguments in the .IRP statement. 
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<real arguments> 

is a list of arguments to be used in the expansion 
of the indefinite repeat range and enclosed in 
angle brackets. Each real argument is a string of 
zero or more characters or a list of real 
arguments (enclosed in angle brackets). The real 
arguments are separated by commas. 

range is the code to be repeated once for each real 
argument in the list. The range may contain macro 
definitions, repeat blocks, or other indefinite 
repeat blocks. Note that only created symbols 
should be used as labels within an indefinite 
repeat range. 

An indefinite repeat block can occur either within or outside macro 
definitions, repeat ranges, or indefinite repeat ranges. The rules 
for creating an indefinite repeat block are the same as for the 
creation of a macro definition (for example, the .MEXIT statement is 
allowed in an indefinite repeat block). Indefinite repeat arguments 
follow the same rules as macro arguments. A second type of indefinite 
repeat block is available which handles character substitution rather 
than argument substitution. The .IRPC directive is used as follows: 

label: .IRPC arg,string 


(range of indefinite repeat) 


.ENDM 

On each iteration of the indefinite repeat range, the dummy argument 
(arg) assumes the value of each successive character in the string. 
Terminators for the string are: space, comma, tab, carriage return, 
line feed, and semicolon. 

Figure 5-6 is an example of .IRP and .IRPC usage. 


IRRTST RT-11 MACRO VM02-09 11104149 PAGE 1 


l 

i 

3 

4 

5 

6 

7 

8 000000 
9 000000 012700 

000056 r 


.TITLE IRPTST 
.LIST MD,MC,ME 
R0*X0 

MOV 4TABLE.H0 
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10 




, IRP 

X,<A,B,C,D,E,F> 

il 






12 




MOV 

X*(RB)♦ 

13 




,EK»DM 



00004 

016720 

000032 


MOV 

A.C«0)+ 


00010 

016720 

000030 


MOV 

8 , (R0)* 


00014 

016720 

000026 

. 

MOV 

C,C«0J♦ 


00020 

016720 

000024 


MOV 

0» CRB)* 


00024 

016720 

000022 


MOV 

E,(R0) ♦ 


00030 

016720 

000020 


MOV 

F,(R0) * 

14 




.IRPC 

Xf abcdef 

15 




.ASCII 

/X/ 

16 

00034 

101 


.ENOM 

.ASCII 

/A/ 


00035 

102 


.ASCII 

/»/ 


00036 

103 


.ASCII 

/c/ 


00037 

104 


.ASCII 

/p/ 


00040 

105 


.ASCII 

/£/ 


00041 

106 


.ASCII 

/ft 

17 






Id 

00042 

041101 

A 3 

• WORD 

"AS 

19 

00044 

041502 

b: 

.WORD 

11 8 C 

20 

00046 

042103 

C 3 

.WORD 

"CD 

21 

00050 

042504 

03 

.WORD 

"Of 

22 

00052 

043105 

E 3 

.WORD 

"EF 

23 

00054 

043506 

Ft 

.WORD 

"FG 

24 

00056 


TABLE 3 

,8LKW 

6 

25 


000001 f 


.END 



Figure 5-6 

•IRP and .IRPC Example 


5,6.7 Repeat Blocks .REPT 

Occasionally it is useful to duplicate a block of code a number of 
times in line with other source code. (.REPT is not available in 
ASEMBL.) This is performed by creating a repeat block of the forms 

labels .REPT expr 


(range of repeat block) 
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ENDM ;OR .ENDR 


where: label is an optional statement label. The .ENDR or 


.ENDM directive may not have a label. A .REPT 
statement occurring within another repeat block, 
indefinite repeat block, or macro definition may 
not have a label associated with it. 


expr is any legal expression controlling the number of 


times the block of code is assembled. Where 
expr<0, the range of the repeat block is not 
assembled. 


range is the code to be repeated expr number of times. 


The range may contain macro definitions, 
indefinite repeat blocks, or other repeat blocks. 
Note that no statements within a repeat range can 
have a label. 



The last statement in a repeat block can be an .ENDM or .ENDR 
statement. The .ENDR statement is provided for compatibility with 
previous assemblers. 

The .MEXIT statement is also legal within the range of a repeat block. 


5.6.8 Macro Libraries: •MCALL 

All macro definitions must occur prior to their referencing within the 
user program. MACRO provides a selection mechanism for the programmer 
to indicate in advance those system macro definitions required by his 
program. 

The .MCALL directive is used to specify the names of all system macro 
definitions not defined in the current program but required by the 
program (not available in ASEMBL)• The .MCALL directive must appear 
before the first occurrence of a macro call for an externally defined 
macro. The .MCALL directive is of the form: 




MCALL argl,arg2 


9 • • • 


where argl,arg2, etc. are the names of the macro definitions required 
in the current program. 

When this directive is encountered, MACRO searches the system library 
file, SYSMAC.SML, to find the requested definition(s). MACRO searches 
for SYSMAC.SML on the system device (SY:). 

See Appendix D for a listing of the system macro file (SYSMAC.SML) 
stored on the system device. 


5.7 CALLING AND USING MACRO 

The MACRO Assembler assembles one or more ASCII source files 
containing MACRO statements into a single relocatable binary object 
file. Assembler output consists of this binary object file and an 
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optional assembly listing followed by the symbol table listing. CREF 
(Cross Reference) listings may also be specified as part of the 
assembly output by means of switch options. 

MACRO is executed using the RT-11 Monitor R command as follows: 

.R MACRO 

The assembler responds by typing an asterisk (*) to indicate readiness 
to accept command string input. In response to the * printed by the 
assembler, the user types the output file specification(s), followed 
by an equal sign or left angle bracket, followed by the input file 
specification(s) in a command line as follows: 


*dev:obj,dev:list/s:arg=dev:sourcel,..,dev:sourcen/s:arg 


where: 

dev: 

is any legal RT-11 device for output; 
must be file-structured for input 


obj 

is the binary object file 


list 

is the assembly listing file containing 
the assembly listing and symbol table 


sourcel, 

.•,sourcen 

are the ASCII source files containing 
the macro source program(s); a maximum 
of six source files is allowed 


/s:arg 

represents a switch and argument as 
explained in Section 5.7.1 


A null specification in either of the output file fields signifies 
that the associated output file is not desired. 


One or more switches can be indicated with the appropriate file 
specification to provide MACRO with information about that file. 

The default case for each file specification is noted below: 


file 

device 

filename 

extei 

object 

DK: 

- 

.OBJ 

listing 

device used 
for object 
output 

— 

.LST 

sourcel 

DK: 

- 

.MAC 

source2 

• 

• 

device used 
for last source 
file specified 

.MAC 

sourcen 

system 

macro 

file 

system device 
SY: 

SYSMAC 

• SML 


Type CTRL C to halt MACRO at any time and return control to the 
monitor. To restart the assembler type R MACRO or the REENTER command 
in response to the monitor's dot. 
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NOTE 

If tC was typed while a CREF listing was 
being produced, the REENTER command may 
not be accepted. In this case, type R 
MACRO to restart the assembler. 


5.7.1 Switches 

There are three types of switch options: listing control switches, 
function switches, and CREF specification switches. The listing 
control switches (/L,/N) provide capabilities similar to those 
described in detail in section 5.5.1.1. The function control switches 
(/D,/E) provide function control as described in Section 5.5.2; 
arguments for these switches are summarized in Section 5.7.1.2. CREF 
control switches allow the user to obtain a detailed cross-referenced 
listing of his assembled file, and are described in detail in Section 
5.7.1.3. Multiple arguments may be specified for a particular switch, 
if desired, by separating each switch value from the next by a colon. 
For example: 

/N:TTM:CND 

These switches turn off teleprinter mode and suppress printing of 
unsatisfied conditionals (as described in the next section). Also, the 
switches are not restricted to appearing near a particular file in the 
command string; /N:TTM, for example, is legal in all of the following 
places: 

*,LP:/N:TTM=source 
*,LP:=source/N:TTM 
*/N:TTM,LP:=source 

and they are all equivalent in function. 


5.7.1.1 Listing Control Switches - A listing control switch (/L for 
list or /N for nolist) is indicated in a command line as follows: 

*dev:obj.ext,dev:list.ext/s:arg=dev:source.ext 

where s:arg represents /L or /N; the remainder of the command line 
abbreviations are as described in Section 5.7. 

The /N switch with no argument causes only the symbol table, table of 
contents and error listings to be produced. The /L switch with no 
arguments causes .LIST and .NLIST directives that appear in the source 
program but have no arguments to be ignored. A summary of the argu¬ 
ments which are valid for the listing control switches follows (refer 
to Section 5.5.1.1 for details): 


Argument 

Default 

Controls listing of 

SEQ 

list 

Source line sequence numbers 

LOC 

list 

Location counter 

BIN 

list 

Generated binary code 

BEX 

list 

Binary extensions 
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SRC 

COM 

MD 

MC 

ME 

MEB 

CND 

LD 

TOC 

TTM 

SYM 


list 

list 

list 

list 

nolist 

nolist 

list 

nolist 

list 

terminal mode 
list 


Source code 
Comments 

Macro definitions , repeat 
range expansions 

Macro calls , repeat range expansions 
Macro expansions 
Macro expansion binary code 
Unsatisfied conditionals, .IF and 
•ENDC statements 

Listing directives with no arguments 
Table of Contents 
Listing output format 
Symbol table 


For example, a command line in the following format allows binary code 
to be listed throughout the assembly using the 132-column line printer 
format: 


*,LP:/L:MEB/N:TTM=FILE 

5.7.1.2 Function Switches - The function control switches (/D for 
disable and /E for enable) are used to enable or disable certain 
functions in source input files and are indicated in the command line 
as follows: 


*dev:obj.ext , dev:lis t.ext=dev:source/s:arg 

/ssarg here represents either /Dsarg or /E:arg. A summary of the 
arguments which are valid for use with the function control switches 
follows (refer to Section 5,5.2 for details): 


Argument 

Default 

Enables or disables 

ABS 

disable 

Absolute binary output 

AMA 

disable 

Assembly of all absolute addresses 
as relative addresses 

CDR 

disable 

Source columns 73 and greater to be 
treated as comments 

FPT 

disable 

Floating point truncation 

LC 

disable 

Accepts lower case ASCII input 

LSB 

disable 

Local symbol block 

PNC 

enable 

Binary output 


For example, the following commands assemble a file allowing all 80 
columns of each card to be used as input (note that since MACRO is a 
two-pass assembler, the cards cannot be read directly from the card 
reader; input from any nonfile-structured device must first be trans¬ 
ferred to a file-structured device before assembly): 

, R PIP 

C ARDS. ft A C - C R ; / A 

, R ft A C R 0 

* * LP: 55 CARDS, ft A C / E i C D R 

Use of either the function control or listing control switches and 
arguments at assembly-time will override any corresponding listing or 
function control directives and arguments in the source program. For 
example , assume the following appears in the source program: 

.NLIST MEB 


MACRO References 


.LIST MEB 
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The "MEB" printing will be disabled for the block indicated; however, 
if /L:MEB is indicated in the assembly command line, both the .NLIST 
MEB and the .LIST MEB will be ignored and the "MEB" printing will be 
enabled everywhere in the program. 

5.7.1.3 Cross Reference Table Generation (CREF) - A cross reference 
table of all or a subset of all symbols used in the source program and 
the statements where they were defined or used can be obtained 
automatically following an assembly by specifying /C:arg with the 
assembly listing file specification (and any listing or function 
control specifications) as follows: 

*dev:obj.ext,dev:list.ext/s:arg/C:arg=dev:source.ext 

/s:arg represents /L:arg, /N:arg, /E:arg, or /D:arg. (If the listing 
device is magtape or cassette, and a CREF listing is desired, the 
handler must first be loaded, using the monitor LOAD command.) 

There are six sections to a complete cross reference listing: 

1. Cross reference of program symbols (i.e., labels used in the 
program and symbols used on the left of the "=" operator). 

2. Cross reference of register-equate symbols (those symbols 
which are defined in the program by a "SYMBOL=%N", 0<=N<=7, 
construct. (Normally this consists of the symbols RO, Rl, 
R2, R3, R4, R5, SP, and PC.) 

3. Cross reference of MACRO symbols (names of macros as defined 
by a .MACRO directive, or as specified in a •MCALL 
directive). 

4. Cross reference of permanent symbols (all operation mnemonics 
and assembler directives). 

5. Cross reference of control sections (those names specified as 
the operand of a .CSECT directive, plus the blank .CSECT and 
the absolute section ". ABS." which are always defined by 
MACRO). 

6. Cross reference of errors (all errors flagged on the listing 
are grouped by error type). 

Any or all of the above sections may be included in the cross 
reference listing as desired. The associated switch options and their 
arguments are listed below: 


Switch 

Argument 

Section Type 

/C:S 

User-defined symbols 

/C:R 

Register symbols 

/CsM 

Macro symbolic names 

/C:P 

Permanent symbols 

/C:C 

(instructions, directives) 
Control sections (.CSECT 

/C:E 

symbolic names) 

Error codes 

/C<no arg> 

Equivalent to /C:S:M:E 
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The specification of a /C switch in a command string causes a 
temporary file, "D^CREF.TMP" , to be generated. If device DK: is 
write-locked or contains insufficient free space for the temporary 
file, the user may allocate the temporary file on another device. To 
do so, a third output file specification is given in the MACRO command 
string? this file is then used instead of DK:CREF•TMP, and is purged 
after use. For example, a command string of this type: 

*,LP:,RK2:TEMP.TMP=SOURCE/C 

causes "RK2:TEMP,TMP" to be used as the temporary file. 

Figure 5-7 illustrates assembled source code and Figure 5-8 contains 
the CREF output. The command line used to produce these listings was: 

*,LP:/C:S:M:R:P:C:E/N:BEX=EXAMPL 

An explanation of the CREF output follows the figures. 
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Cross reference tables, if requested, are generated at the end of a 
MACRO assembly listing. Each table begins on a new page (the tables 
in Figure 5-8 have been consolidated due to space considerations). 
Symbols, control sections, and error codes are listed at the left 
margin of the page; corresponding references are indicated next to 
them across the page from left to right. A reference is of the form 
p-1, where p is the page on which the symbol, control section, or 
error code appears, and 1 is the line number within the page. A 
number sign (#) appears next to a reference wherever a symbol has been 
defined. An asterisk appears next to a reference wherever a 
destructive reference has been made to the symbol (i.e., the contents 
of the location defined by that symbol has been altered at that 
point). 

The CREF output requested in the preceding figures included user 
defined symbols, macro symbolic names, control sections, error codes, 
register symbols, and permanent symbols. Since no errors were 
generated in this assembly, no CREF output for error codes was 
produced. 


5.8 MACRO ERROR MESSAGES 

MACRO error messages enclosed in question marks are output on the 
terminal. The single-letter error codes are printed in the assembly 
listing. 

In terminal mode these error codes are printed following a field of 
six asterisk characters and on the line preceding the source line 
containing the error. For examples 


****** a 

26 00236 000002 1 .WORD REL1+REL2 


Error Code 


Meaning 


A 


Addressing error. An address within the instruction is 
incorrect. Also may indicate a relocation error. The 
addition of two relocatable symbols is flagged as an A 
error. May also indicate that a local symbol is being 
defined more than 128 words from the beginning of a 
local symbol block. 


B 


Bounding error. Instructions or word data would be 
assembled at an odd address in memory. The location 
counter is updated by +1. 


D 


Multiply-defined symbol referenced. Reference was made 
to a label (not a local label) that is defined more than 
once. 


E 


End directive not found. (A .END is generated.) 


I 


Illegal character detected. Illegal characters which 
are also non-printing are replaced by a ? on the 
listing. The character is then ignored. 


L 


Line buffer overflow, i.e., input line greater than 132 
characters. Extra characters on a line are ignored in 
terminal mode. 
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M Multiple definition of a label. A label was 

encountered which was equivalent (in the first six 
characters) to a previously encountered label. 

N Number containing 8 or 9 has decimal point missing. 

0 Opcode error. Directive out of context. 

P Phase error, A label's definition or value varies from 

one pass to another or a local symbol occurred twice 
within a local symbol block. 

Q Questionable syntax. There are missing arguments or 

the instruction scan was not completed or a carriage 
return was not immediately followed by a line feed or 
form feed. 

R Register-type error. An invalid use of or reference to 

a register has been made. 

T Truncation error. A number generated more than 16 bits 

of significance or an expression generated more than 8 
bits of significance during the use of the .BYTE 
directive. 

U Undefined symbol. An undefined symbol was encountered 

during the evaluation of an expression. Relative to 
the expression, the undefined symbol is assigned a 
value of zero. 

Z Instruction which is not compatible among all members 

of the PDP-11 family. 


Error Message Explanation 

?BAD SWITCH? The switch specified was not 

recognized by the program. 

7INSUFFICIENT CORE? There are too many symbols in the 

program being assembled. Try 
dividing program into 

separately-assembled subprograms. 

?I/0 ERROR ON CHANNEL n? A hardware error occurred while 

attempting to read from or write to 
the device on the channel specified 
in the message. (Channel numbers 
(0<=n<=10 octal) are assigned to 
files in the manner described in 
Section 9.4.7, Chapter 9.) 

Note that the CREF temporary file 
is on channel 2 even if it was not 
specified in the command string 
(i.e., if the default file 
DKsCREF.TMP is used). 
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?N0 INPUT FILE? 

No input file was specified and 
there must be at least one input 
file. 

70UTPUT DEVICE FULL? 

No room to continue writing output. 
Try to compress device with PIP. 

TOO MANY OUTPUT FILES 

Too many output files were speci¬ 
fied. 


All CREF error messages begin with C- to distinguish them from MACRO 
error messages. When a CREF error occurs, the error message is prin¬ 
ted on the console terminal and CREF chains back to MACRO; MACRO 
prints an asterisk, at which time another command line may be entered 

Error Message Explanation 


?C-CHAIN-ONLY-CUSP? 

An attempt was made either to "R 
CREF" or to "START" a copy of CREF 
which was in memory. CREF can only 
be "chained" to. 

?C-CRF FILE ERROR? 

An output error occurred while 
accessing "DK:CREF.TMP", the tem¬ 

porary file passed to CREF. 

?C-DEVICE? 

An invalid device was specified to 
CREF. 

?C-LST FILE ERROR? 

An output error occurred while 
attempting to write the cross- 
reference table to the listing file 
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CHAPTER 6 
LINKER 


6.1 INTRODUCTION 


The RT-11 Linker converts object modules produced by either one of the 
11 assemblers or FORTRAN IV into a format suitable for loading and 
execution. This allows the user to separately assemble a main program 
and each of its subroutines without assigning an absolute load address 
at assembly time. The object modules of the main program and 
subroutines are processed by the Linker to: 


1. Relocate each object module and assign absolute addresses 


2 . 


Link the modules by correlating global symbols defined in 
module and referenced in another module 


one 


3. Create the initial control block for the linked program 

4. Create an overlay structure if specified and include the 
necessary run-time overlay handlers and tables 


5. 

6 . 


Search user specified libraries to locate unresolved globals 

Optionally produce a load map showing the layout of the load 
module 


The RT-11 Linker requires two or three passes over the inout mndnioo 

a?fcLSol fir ^- PaSS ifc bonstru <*s the global symbol tSl e, including 
libra™*^ ® ectlon nf^es and global symbols in the input modules. If 
a ? y 31:6 to linked with input modules, an intermediate 

13 needed to force the modules resolved from the library file 
fc i r °°^ segroent (that part of the program which is never 

°p®f r . aid ’ Du rmg the final pass, the Linker reads the object modules 
performs most of the functions listed above, and produces a loJd 

module .LDA for use with the Absolute Loader, save^mage ( sJv) for t 
Single-]ob system or for the background job of L F VsvL-L La 

relocatable (.REL) format for the foreground job of ^ F/B System). 

The Linker runs in a minimal RT-11 system of UK- an,, 

must be at least one random-access device (diqk n-r -f nere 

image or relocatable format output. DECtape) for save 
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6.2 CALLING AND USING THE LINKER 
To call the Linker, type the command: 


R LINK 

and the RETURN key in response to the Keyboard monitor's dot. The 
Linker prints an asterisk and awaits a command string. 

Tvpe CTRL C to halt the Linker at any time and return control to the 
monitor. To restart the Linker, type R LINK or the REENTER command in 
response to the monitor's dot. The Linker outputs an extra line feed 
character when it is restarted with REENTER or after an error in the 
first command line. When the Linker is finished linking, control 
returns to the CSI automatically. An extra line feed character 
precedes the asterisk printed by the CSI. 


6.2.1 Command String 

The first command string entered in response to the Linker's asterisk 
has the following format: 

*dev:binout,dev:mapout=dev:obj1,dev:obj 2,..,/sl/s2/s3 


where: 

(j ev: is a random-access device for all files except 

dev:mapout, which can be any legal output de¬ 
vice. If dev: is not specified, DK is assumed. 
If the output is to be LDA format (that is, 
the /L switch was used), the output file need 
not be on a random-access device. 


binout 


mapout 
obj1,.. • 


/s1/s2/s3 


is the name to be assigned to the Linker's 
save image, LDA format, or REL format output 
file. This file is optional: if not 
specified, no binary output is produced. 
(Save image is the assumed output format 
unless the /L or /R switches are used.) 

is the optional load map file. 

jure files of one or more object modules to be 
input to the Linker (these may be library 
files). 

jure switches as explained in Table 6-1 and 
Section 6.8. 


If the /C switch is given, subsequent command lines may be entered as: 


*objm,objn,.../sl/s2 

The /C switch is necessary only if the command string will not fit on 
one line or if the overlay structure is used. If an error occurs in a 
continued command line (e.g., 7PILE NOT FND?), only the line in error 
need be retyped. 
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If an output file is not specified, the Linker assumes tha<- fha 
associated output is not desired. For example, if the load module and 

bJ a the a EiSer? 0t 8pecified ' onl y error messages (if any) are pointed 
The default values for each specification are* 


Device 


Load Module 
Map Output 


DK: 

Same as 
load module 

Object Module DK: or same 
as previous 
object module 


Filename Extension 

none SAV, REL(/R), LDA(/L) 

none MAP 

none OBJ 


^««.!r ta V rr ° r is mad ® in a command string, an error message is 
asterisk. nW comaand string can then be typed following the 

If a nonexistent file is specified a fatal error occurs; control is 
returned to the command string interpreter, an asterisk is printed and 
a new command string may be entered. 


6.2.2 Switches 







Table 6-1 
Linker Switches 


Switch 

Name 

Command 

Line 

Meaning 

/A 

1st 

Alphabetizes the entries in the load map. 

/Bsn 

1st 

Bottom address of program is indicated as 
n (illegal for foreground links). 

/c 

any 

Continues input specification on another 
command line. Used also with /0. 

/F 

1st 

Instructs the Linker to use the default 
FORTRAN library, FORLIB.OBJ; note that 

FORLIB does not have to be specified in 
the command line. 

/I 

1st 

Includes the global symbols to be 

searched from the library. 

/L 

1st 

Produces an output file in LDA format 
(illegal for foreground links). 


(Continued on next page) 
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Table 6-1 (Cont.) 
Linker Switches 


Switch 

Name 

Command 

Line 

Meaning 

/M or 
/Msn 

1st 

Stack address is to be specified at the 
terminal keyboard or via n. 

/0:n 

any but 
the 1st 

Indicates that the program will be an 
overlay structure; n specifies the 
overlay region to which the module is 
assigned. 

/R 

1st 

Produces output in REL format; only 
files in REL format will run in the 
foreground (REL format files may not be 
run under a Single-Job system) 

/s 

1st 

Allows the maximum amount of space in 
memory to be available for the Linker's 
symbol table. (This switch should only 
be used when a particular link stream 
causes a symbol table overflow.) 

/T or 
/Tsn 

1st 

Transfer address is to be specified at 
terminal keyboard or via n. 


6.3 ABSOLUTE AND RELOCATABLE PROGRAM SECTIONS 

A program produced by one of the RT-11 assemblers or FORTRAN IV can 
coSsiS of an absolute program section, declared by the .ASECT 
assembler directive, and relocatable program sections declared by the 
.CSECT assembler directive. A .CSECT directive is assumed at the 
beginning of the source program. The instructions and data in 
relocatable sections are normally assigned locations beginning at 
1000(octal) or 0 for a foreground link. The assignment of addresses 
can be influenced by command string switches and the size of the 
absolute section (.ASECT, if present). Each control section is 
assigned a memory address; the Linker then appropriately modifies all 
instructions and/or data as necessary to account for the relocation of 
the control sections• 


NOTE 


Foreground programs cannot use .ASECTs 
beyond 1000 (octal); as a general 
practice, they should be avoided under a 
Foreground/Background system. 


The RT-11 Linker handles the absolute section as well as the named and 
unnamed control sections. The unnamed control section is internal to 
each object module. That is, every object module can have an unnamed 
control section but the Linker treats each control section 
independently. Each is assigned an absolute address such that it 
occupies an exclusive area of memory. Named control sections, on the 
other hand, are treated globally; if different object modules have 
control sections with the same name, they are all assigned the same 
absolute load address and the size of the area reserved for loading of 
the section is the size of the largest. Thus, named control sections 
allow for the sharing of data and/or instructions among object 
modules. This is the same as the handling and function of COMMON in 
FORTRAN IV. The names assigned to control sections are global and can 
be referenced as any other global symbol. 
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NOTE 


If relocatable code is to be linked for 
the foreground, no location may be filled 
more than once (using location counter 
arithmetic).; any such location may be 
improperly relocated during the FRUN and 
may cause program or system failure. 

For example, the following code illustrates 
a program using location counter arithmetic 
that is illegal if linked for the foreground. 
Note that the code at line 15 starts at 0 due 
to location counter modification. To correct 
this program for foreground linking, remove 
all .=.- instructions. 




.MAIN. RT-11 MACRO VM02-12 RAGE 1 



t 

2 

3 




.CSECT TEST 
,GLOBL A,B* C 
.MCALL .. V2. .».REGDEF 
..V2.. 

.REGDEF 
.WORD A 
MOV A*6,Ri 


4 000000 

5 000000 


6 000000 000000G 
T 000002 016701 START | 
000006G 


o 


S 000006 060127 

9 000010 000000G 

10 000002 ' 

11 00002 000004G 

12 000002 ' 

13 00002 000002G 

14 000000' 

15 00000 000006G 

16 000002' 


ADO Rl, (PC5 + 
.WORD B 
,■.•10 
.WORD A+4 
.».-2 
.WORD B*2 
• ■••4 
.WORD C+6 
.END START 
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6.4 GLOBAL SYMBOLS 

Global symbols provide the link, or communication, between object 
modules. Global symbols cure created with the .GLOBL assembler 
directive (see Chapter 5). If the global symbol is defined in an 
object module (as a label or by direct assignment), it is called an 
entry symbol and other object modules can reference it. If the global 
symbol is not defined in the object module, it is an external symbol 
and is assumed to be defined (as an entry symbol) in some other object 
module. 

As the Linker reads the object modules it keeps track of all global 
symbol definitions and references. It then modifies the instructions 
and/or data which reference the global symbols. Undefined globals are 
printed on the console terminal after pass 1 (or pass 2 if a library 
file is also linked). 


6.5 INPUT AND OUTPUT 

Linker input and output is in the form of modules; one or more input 
modules (object files produced by either assembler or FORTRAN IV) are 
used to produce a single output (load) module. 


6.5.1 Object Modules 

Object files, consisting of one or more object modules, are the input 
to the Linker (the Linker ignores files which are not object modules). 
Object modules are created by the RT-11 assemblers or FORTRAN IV. The 
Linker reads each object module at least twice (three times if library 
files are linked). During the first pass each object module is read to 
construct a global symbol table and to assign absolute values to the 
control section names and global symbols. If library files cure 
linked, a second pass is needed to resolve the undefined globals from 
the library files and force their associated object modules into the 
root; on the final pass, the Linker reads the object modules, links 
and relocates the modules and outputs the load module. 


6.5.2 Load Module 


The primary output of the Linker is a load module which may be loaded 
and run under RT-11. The load module is output as a save image file 
(SAV) for use under a Single-Job system or the background job. Under 
an F/B System, the /R switch must be used to produce a REL 
(reloctable) format foreground load module if the job is to run in the 
foreground. An absolute load module (LDA) is produced if the module 
is to be loaded by the Absolute Loader. 


The load module for a save image file is arranged as follows: 


Root Segment 


Overlay 

Segments 

(optional) 


For a REL image file, the load modules are arranged as: 
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Root Segment 

Overlay 

Resident 

Overlay 

Segments 

REL 

REL Blocks 


(optional) 

Blocks 

(optional) 


The first 256-word block of the root segment (main program) contains 
the memory usage map and the locations used by the Linker to pass 
program control parameters. The memory usage map outlines the blocks 
of memory used by the load module and is located in locations 360 to 
377. 

The control parameters are located in locations 40-50 and contain the 
following information when the module is loaded: 


Address 


Information 


40: Start Address of program 

42: Initial setting of R6 (stack pointer) 

44: Job Status Word 

46: USR Swap Address (0 implies normal location) 

50: Highest Memory Address in user's program 


For a foreground link the following additional parameters contain 
information: 


34,36: TRAP Vector 

52: Size of Resident (words) 

54: Sum of the Resident and largest Overlay Region 

(words) 

56: F/B Identification 

60: Address of Resident REL Block 


Memory locations 0-476 (comprising the interrupt vectors and system 
communication area) may be assigned initial values by using an .ASECT 
assembler statement and will appear in block 0 of the load module, but 
there are restrictions on the use of .ASECTs in this region. The 
Linker does not permit an .ASECT of location 54 or of locations 
360-377 (the memory usage map is passed in those locations)• In 
| addition, for foreground links, an .ASECT of words 40-60 is not 
permitted (additional parameters are passed to FRUN in those 
locations)• 


Any location which is not restricted may be set with an .ASECT, but 
caution should be used in changing the system communication area. 
Restricted areas, such as the region 360-377, must be initialized by 
the program itself. There are no restrictions on .ASECTs if the 
output format is LDA. 

Locations in the region 0-476 which are initialized by an .ASECT in a 
program may never be loaded when the program is executed. There are 
two reasons for this. For background tasks (or the Single-Job system) 
the R, RUN, and GET commands will not load an address protected by the 
monitor's memory protection map. The addresses normally protected 
include such important areas as the system device and console device 
vectors, but protection may be extended dynamically (e.g., by a 
foreground task issuing a .PROTECT call). For foreground tasks, the 
FRUN command will load only locations 34-50 (34 is the TRAP 
instruction vector) and all other .ASECTs are ignored. The procedure 
for loading these locations is to do so at run-time using MOV 
instructions. 
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6,5.3 Load Map 

i^J?2Y e8 ™# a * oad ™ a P is Produced following the completion of the 
initial pass(es) of the Linker. This map, shown in Figure 6-1 
diagrams the layout of memory for the load module. 

Each.CSECT included in the linking process is listed in the load map. 
anH ®”^ ry for f* c ® E ^ T includes the name and low address of the section 

noiniq K n i b w S ^ remaining columns contain the entry 

points (or globals) found in the section and their addresses. 


The map begins with the name of the load module and the date of 
Th f m ° d nles located in the root segment of the load module 
are listed next, followed by those modules which were assigned to 

unflpf^ S H K°f der K b ¥ their re 9 ion number (see Section 6.6). Any 
undefined global symbols are then listed. The map ends with the 

transfer address (start address) and high limit of relocatable code. 


NOTE 

The load map will not reflect the 
absolute addresses for a REL file 
created to be run as a foreground job; 
the base relocation address specified at 
FRUN time must be added to obtain the 
absolute addresses. 

WSLTST^ 11 ^ 16 * assuine the FRUN command is used to run the program 


.FRUN RELTST/P 
LOADED AT 137150 

When linked, the following load map is produced: 


RTM1 LINK 

X03M6 

LOAD MAP 





reltst. 

REL 


03-SEP- 

74 





SECTION 

AOOR 

SIZE 

ENTRY 

AOOR 

ENTRY 

AOOR 

ENTRY 

AOOR 

. ASS. 

0001900 

000350 

STKSIZ 

000012 

SF VEC 

000320 

SCRPOS 

001750 

TSTVTl 

000390 

000326 







SQTB 

000676 

001116 

SDSINT 

000676 

SSTORP 

000710 

SNR 

000752 




STACKP 

000764 

STATBF 

001106 

SOPC 

001142 




SL1NKF 

001146 

SLCDIS 

001150 

SLCNT 

001152 




SOSVEC 

001154 

STACKE 

001202 

30FILE 

001226 




SYS 

001244 

S6LANK 

001246 

SLINK 

001252 




S8YPAS 

001256 

SCTPAK 

001260 

SLSRA 

001276 




SCUSER 

001302 

SNULL 

001316 

SXT 

001326 




SYT 

001330 

SLPINT 

001404 

SLPBUF 

001434 




SNR8UF 

001446 

STRAKC 

001562 

SXSTOR 

001572 




SYSTOR 

001574 

SSOINT 

001670 

SVSTIN 

001676 




SVSTP 

001722 

SPDV1 

001756 

SPEXIT 

001764 
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OVERLAY 

SGT1 

SGT2 

SGT3 

RE6X0N 

002016 

002226 

002330 

000001 

000210 

000102 

000130 

SEGMENT 

SVINIT 

SVN8RT 

SVBLNK 

SVTRAK 

SN0SYN 

000001 

002016 

002130 

002226 

002330 

002430 

SVFOEL 

SVRM0V 

SVR8TR 

SVLPEN 

88YNC 

002100 

002174 

002256 

002410 

002440 

8V8T0P 

SVSTRT 

SVSRCH 

8V8TPM 

SNAME 

002114 

002214 

002300 

002420 

002450 

OVERLAY 

SGT4 

REGION 

002016 

000001 

000602 

SEGMENT 

SYRTLK 

SV8CRL 

000002 

002016 

002512 

8VUNLK 

002300 

SVLSET 

002404 


TRANSFER ADDRESS ■ 000350 
HIGH LIMIT « 002620 


To determine the address of TSTVTl, 
thus 137520 is the absolute address 
is 137150 plus 350, or 137520. 


137150 must be 
of TSTVTl. The 


added to 000350; 
transfer address 


6.5.4 Library Files 

The RT-11 Linker ha. the capability of «*5«?g2_SSSS5 

libraries. Libraries °??P°|*i an °£ rogram ^chapter 7) which 

formatted files produced by the librarian progr provide 

contain one or more ° b 7 uger in meeting specific programming 

routines and functions to ^ M . special library containing all 

needs. (For example, FORTRAN has a special lidt y ^ using the 

necessary computational ^ unc . UD dated so that routines which 

Librarian, libraries can be cre ^®J s ^ i ^ d ^r u s° d by m0 re than one 

ere used ‘X^^t'ly .cce^el select'ef modules from the 

program, may be easi y needed with the user program to 

pKS la on.1oS y r^ite“ Libraries are further described in Section 

6.7 and in Chapter 7. 


NOTE 

Library files that have been combined 
under PIP are illegal as input to both 
the Linker and the Librarian. 
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RT-11 

LINK 

V03-01 

LOAD MAP 





SORT 

.SAV 


19.SEP- 

74 





SECTION ADDR 

SIZE 

ENTRY 

ADDR 

ENTRY 

ADDR 

ENTRY 

ADDR 

• A8S. 

000000 

001000 

SUSRSR 

000000 

SV005A 

000001 

SNLCHN 

000006 




SLRECl 

000210 

STRACE 

004737 




001000 

000220 








001220 

001364 

SQTI 

001246 






002604 

002300 

OCU 

002604 

ICIS 

002612 

SGET 

002772 




PC I $ 

003006 

ocos 

003712 

ICOS 

003720 




GC OS 

004144 

FCOS 

004152 

ECOS 

004156 




DCOS 

004164 






005104 

000160 

ISN$ 

005104 

SISNTR 

005110 

LSNS 

005124 




SLSNTR 

005130 






005264 

000102 

HOISSS 

005264 

MQLSSS 

005264 

M0IS3M 

005270 




MO I $ S A 

005274 

MOISIS 

005300 

MOLSIS 

005300 




PELS 

005300 

MOISIM 

005304 

MOISIA 

005310 




MQISMS 

005314 

MO I $ MM 

005320 

MOISMA 

005324 




MOIS0S 

005330 

MOIS0M 

005334 

M 0 I $ 0 A 

005340 




N0IS1S 

005344 

MOISIM 

005352 

MOISIA 

005360 


005366 

000020 

IFRS 

005366 

IFWS 

005400 




005406 

000046 

EOLS 

005406 






005454 

000062 

TVLS 

005454 

TVFS 

005462 

TVOS 

005470 




TVQS 

005476 

T V PS 

005504 

TVIS 

005512 


005536 

000036 

CAIS 

005536 

CALS 

005544 




005574 

000174 

SORT 

005574 






005770 

000026 

MOFSRS 

005770 

MOFSRM 

005776 

MOFSRA 

006006 




MOFSRP 

006012 






006016 

000044 

nmjsim 

006016 

NMIS1I 

006026 

BLES 

006034 




BEGS 

006036 

BGTS 

006044 

BGES 

006046 




BRAS 

006050 

bnes 

006054 

blts 

006056 


006062 

000072 

FOOS 

006062 

EXIT 

006074 

STPS 

006074 


006154 

000002 

SAOTS 

006154 





SERRTB 

006156 

000100 







SERRS 

006256 

002637 








011116 

001534 

$F I 0 

011600 






012652 

000202 

SFMTDR 

012652 

SFMTDN 

012702 

SINITI 

012750 


013054 

000416 

SCLOSE 

013054 






013472 

000106 

ICIS 

013472 

LCDS 

013540 




013600 

000302 

SGETRE 

013600 

STTYIN 

013722 




014102 

000262 

SPUTRE 

014102 






014364 

000106 

SFChNL 

014364 






014U72 

000674 

SOPEN 

014472 






015366 

000110 

SOUMPL 

015366 






015476 

000414 

SPUTBL 

015476 

SGETBL 

015676 

SEOFIL 

016046 


016112 

000042 

SR A I T 

016112 






TRANSFER ADDRESS ■ 001000 
HIGH LIMIT ■ 01615A 


Figure 6-1 

Linker Load Map for Background Job 
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6.6 USING OVERLAYS 

The RT-11 program overlay facility enables the user to have virtually 
unlimited memory space for an assembly language or FORTRAN program. A 
program using the overlay facility can be much larger than would 
normally fit in the available memory space, since portions of the 
program (called overlay segments) reside on a backup storage device 
(disk or DECtape)• 

The RT-11 overlay scheme is a strict multi-region arrangement; it is 
not tree-structured. Figure 6-2 diagrams this scheme. The overlay 
system which the user constructs from his completed program is 
composed of a root segment, memory-resident overlay regions, and the 
overlay segments stored on the backup storage device. The root 
segment is a required part of every overlay program and contains all 
transfer addresses; it must therefore never be overlaid. An overlay 
region corresponds to a run-time area of memory that is shared by two 
or more subroutines (called co-resident subroutines); there is a 
distinct memory area for each overlay region. Overlay segments are 
portions of the save image or REL format file from which the user*s 
program is run; these are brought into memory as needed. 


A=A/C 

= Root ^ 


B/O:1/C 

= Segment 1 \ 

= Region 1 

C/O:1/C 

= Segment 2 ^ 


D/O:2/C 

= Segment 3 ^ 

= Region 2 

E/0:2 

= Segment 4 J 



Figure 6-2 
Overlay Scheme 



Overlay regions are specified to the Linker via the /0 switch as 
described in Section 6.8.8. The size of the overlay region is 
calculated by the Linker to be the size of the largest group of 
subroutines that can occupy the region at one time. The Linker 
creates the overlay regions and edits the program to produce the 
desired overlays at run-time. 

Figure 6-3 shows a diagram of memory for a program which has an 
overlay structure and Figure 6-4 is a listing of the run-time overlay 
handler. 


6-10 



Linker 


ADDRESS 

0 

400 


SYSTEM AREA 


OVERLAY HANDLER 
(INCLUDED BY B UNKER) 


ROOT SEGMENT 
OF PROGRAM 
(BASICR.FPMP) 


IDENTIFICATION WORD 


OVERLAY REGION 1 


(BASICX) 


(BASICE) 


IDENTIFICATION WORD 


OVERLAY REGION 2 
(BASICH) 


MONITOR 


Figure 6-3 

Memory Diagram Showing BASIC Link With Overlay Regions 


.5BTTL the Run-time OVERLAY HANQLER 

I the following cuue is included in the user's program by the 
l linker whenever overlays are reuuested by the user, 

I 56.6 MICROSECONDS (APPROX) IS ADOED TO EACH REFERENCE OF 
/ A RESIDENT OVtRLAY SEGMENT. 

| THt RUN-TIME OVERLAY HANDLER IS CALLEO BY A DUMMY 
/ SUBROUTINE OF The FOLLOWING FORMI 

f JSR R5,$QVRH /CALL TO COMMON CODE 

/ .WORD ^OVERLAY Up tU OF DESIRED SEGMENT 

I ,WORQ «ENTRY ADDRw /ACTUAL CORE ADOR 

/ one dummy routine of the above form is stored in the resident 
/ portion of the usgR's program for each entry point to 
/ AN overlay segment, all references to the ENTRY point are 
/ modified by The uinker to insteao be references to the appro- 
/ priaTe dummy routine, each overlay segment is called into 
/ CORE as a unit A n 0 must be contiguous in CORE, an OVERLAY 
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l SEGMENT M*Y ruVt ANY NUMBER OF ENTRY POINTS# TO THE LIMITS 
I OF cost memory• ONLY ONE SEGMENT AT a time may occupy an 

; OVERLAY REGION, 

SINCE REFERENCES TO OVERLAY SEGMENTS ARE AUTOMATICALLY TRANS- 
l LAIEO BY THE LINKER INTO REFERENCES TO OUmMY SUBROUTINES# 

| the programmer MUST not attempt to reference data In an over. 


F LAY BY 

1 USING 

GLOBAL SYMBOLS, 


aOVTABMQBB + SUVRHEOOVRH 

SOVRHl 

MU V 

Rgi # • (SP) 


MU V 

R1#-(5P) 

SOyRMBI 

MOV 

R2#-tSP) 

F 

MOV 

(R5)♦# R0 

BR 

SFIRST 


MOV 

R0»R1 

sovrhai 

AOD 

#$0VTAB.6,R1 


MOV 

(R1)♦» R2 


UMP 

RB # #R2 


BEQ 

SENTEH 


•HEADm 

17#n 2,CRl)♦# (Rl) 


BCS 

serr 

SEnTErI 

MOV 

(SP)*# R2 


MOV 

CSPJ♦# R1 


MOV 

C5P)♦# R0 


MOV 

•RB,RS 


RTS 

RS 

SFIRSTI 

MOV 

<*12500# SOVRHB 


MOV 

CPC)+#R1 

SHROOTI 

• WORD 

0 


MOV 

CPC)*#R2 

SHOVLVI 

.WORD 

0 

JSI 

CLR 

CRD* 


CMP 

R1#H2 


BLO 

IS 


BR 

SOVRHB 

SERRl 

EMT 

376 


.BYTE 

0,373 


f p i ck UP OVERLAY number 
F FIRST call only * * * 

|CALC TABLE AOOR 

I SET CORE AOOR OF OVERLAY REGION 
|IS OVERLAY ALREADY RESIDENT? 

F YES# BRANCH TO IT 


FRESTORE USER'S REGS 


|GET ENTRY ADDRESS 
FENTER OVERLAY ROUTINE 
FRESTORE USER'S RS 


AND 


FRESTORE SWITCH INSTR 
FSTART AOOR FOR CLEAR OPERATION 
FHIGH AOOR OF ROOT SEGMENT 
F COUNT 

FHIGH LIMIT OF OVERLAYS 
fclear all overlay REGIONS 


FAND RETURN TO CALL IN PROGRESS 
F GENERATE ALWAYS fatal error 
FAND DISREGARD SOFT ERROR 


SOVRHgl 


F OVERLAY SEGMENT TaBLE FQLLOwSl 

F SOVTABJ ,wORD «CORE AQOR>#«RELATIv£ 8LK»,<wQR0 COUNT* 

f Three wurqs per entry, one entry per overlay segment. 

F ALSO# there IS ONE WORO PREFIXED TO EACH OVERLAY REGION 
F That IDENTIFIES The segment CURRENTLY RESIDENT IN THAT REGION, 
F THIS word is an INDEX into the sqvtab TABLE. 


Figure 6-4 

The Run-Time Overlay Handler 
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There is no special code or function call needed to use 
the following rules must be observed when referencing 
user program which might be overlaid. 


overlays but 
parts of the 


1 . 


Calls or branches to overlay segments must be made directly 
to entry points in the segment. Entry points are locations 
r a ? g ?^ Wlth a global symbol (refer to Chapter 5, Section 
5.5.10). For example, if ENTER is a global tag in an overlay 
segment: J 


JMP ENTER is legal, but 

JMP ENTER+6 is illegal. 

2. Entries in overlay segments can be used only for transfer of 
control and not for referencing data within an overlay 
section (e.g., MOV ENTER,R4 is illegal if ENTER is in an 
overlay segment, but MOV #ENTER,R7 is legal because it is 
used for transfer of control). A violation of this rule 
cannot be detected by the assembler or Linker so no error is 
issued; however, it can cause the program to use incorrect 
data. 

3. When calls are made to overlays, the entire return path must 
be in memory. This will happen if these rules are followed: 

Calls (with expected return) may be made from an overlay 
segment only to entries in the same segment, the root 
segment, or an overlay segment with a greater region 
number. 

Calls to entries in the same region as the call must be 
entirely within the same segment, not another segment in 
the same region. 

Jumps (with no expected return) can be made from an 
overlay segment to any entry in the program. However, 
jumps should not reference an overlay region whose number 
is lower than the region from which the last unreturned 
call was made (e.g., if a call was made from region 3, 
then no jumps should reference regions 1, 2 or 3 until 
the call has returned). 

Subroutines in the root segment may be called from 
overlay segments; in turn, they may call entries from 
the same overlay segment which called them, or from the 
root segment, or from another overlay segment with a 
greater region number. Such subroutines are considered 
part of the overlay segment which called them. 

4. A .CSECT name cannot be used to pass control to an overlay. 
It will not cause the appropriate segment to be loaded into 
memory (e.g., JSR PC,OVSEC is illegal if OVSEC is used as a 
•CSECT name in an overlay). As stated in 1 above, a global 
symbol must be used to pass control from one segment to the 
next. 

5. Channel 17(octal) cannot be used by the user program because 
overlays are read on that channel. 

6. Object modules acquired from a library file cannot be placed 
into overlays. 
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7. Library files may not be specified on the same command line 
as an overlay. 

8 Overlay regions must be specified in ascending order and are 
read-only. Unlike USR swapping, an overlay segment does not 
save the segment it is overlaying. Any tables, variables, or 
instructions that are modified within a given overlay segment 
are re-initialized to their original values in the SAV or REL 
file if that segment has been overlaid by another segment. 
Any variables or tables whose values must be maintained 
across overlays should be placed in the root segment. 

9. .ASECTs of any size in an overlay foreground link are 
illegal; the error message ?ILL ASECT? is printed and the 
line is aborted. 

The following information should be noted when writing FORTRAN 
overlays. 

1. When dividing a FORTRAN program into a root segment and 
overlay regions (and subsequently dividing each overlay 
region into overlay segments), routine placement should be 
carefully considered. The user should always remember that 
it is illegal to call a routine located in a different 
overlay segment in the same overlay region, or an overlay 
region with a lower numeric value (as specified by the Linker 
overlay switch, /Osn) from the calling routine. The user 
should divide each overlay region into overlay segments which 
never need to be resident simultaneously (i.e., if segments A 
and B are assigned to region X, they cannot call each other 
because they occupy the same locations in memory)• 

2. The FORTRAN main program unit must be placed in the root 
segment. 

3. In an overlay environment, subroutine calls and function 
subprogram references may refer only to one of the following: 

A FORTRAN library routine (e.g., ASSIGN, DCOS) 

A FORTRAN or assembly language routine contained in the 
root segment 

A FORTRAN or assembly language routine contained in the 
same overlay segment as the calling routine 

A FORTRAN or assembly language routine contained in a 
segment whose region number is greater than that of the 
calling routine 

4. In an overlay environment, COMMON blocks must be placed so 
that they are resident when referenced. Blank COMMON is 
always resident since it is always placed in the root 
segment. All named COMMON must be placed either in the root 
segment, or into the segment whose region number is lowest of 
all segments which reference the COMMON block. A named 
COMMON block cannot be referenced by two segments in the same 
region unless the COMMON block appears in a segment of a 
lower region number. The Linker automatically places a 
COMMON block into the root segment if it is referenced by the 
FORTRAN main program or by a subprogram that is located in 
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5. 


the root segment:. Otherwise the Linker places a COMMON block 
in the first segment encountered in the Linker command strine 
that references that COMMON block. 

All COMMON blocks which are initialized (by use of DATA 
statements) must be so initialized in the segment in which 
they are placed. 


Refer to the RT-ll/RSTS-11 FORTRAN IV User's Guide for more details. 

ThS never takes part in overlaying in any way (i.e., if part of 
an .ASECT is destroyed by overlay operations, it is not restored by 
the overlay handler). y 

The aforementioned sets of rules apply only to communications among 
the various modules that make up a program. Internally, each module 
must only observe standard programming rules for the PDP-11 (as 
described in the PDP-11 Processor Handbook and in Chapter 5). 

It should be noted that the condition codes set by a user program are 
not preserved across overlay segment boundaries. 

The Linker provides overlay services by including a small resident 
overlay handler (Figure 6-4) in the same file with the user program to 
be used at program run-time. This overlay handler plus some tables 
are inserted into the user's program beginning at the bottom address 
computed by the Linker. The Linker moves the user's program up in 
memory by an appropriate amount to make room for the overlay handler 
and tables, if necessary. 


6.7 USING LIBRARIES 

Libraries are specified in a command string in the same fashion as 
normal modules; they may be included anywhere in the command strinq, 
with the exception of overlay lines, if a global symbol is undefined 
a '- time the library is encountered in the input stream and a 

moduie is included in the library which includes that global 
definition, that module is pulled from the library and linked into the 
load image. Only the modules needed to resolve references are pulled 
from the library; unused modules are not linked. 

NOTE 

Modules in one library may call modules 
fanother library; however, the 
libraries must appear in the command 
string in the order in which they are 
called. For example, assume module X in 
library ALIB calls SQRT from the FORTRAN 
library. To correctly resolve all 
globals, the order of ALIB and the 
FORTRAN library should appear in the 
command line as: 

*Z=B t ALIB/F 
or t 'l = B v A LIB y F 0 R LIB 
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Module B is the root. It calls X from 
ALIB and brings X into the root. X in 
turn calls SQRT which is brought from 
FORLIB into the root. 


FORTRAN libraries cannot precede their root segment in a command line 
as this creates a bad transfer address. For example: 


#X=ROOT/F 
>KX=ROOT r FORLIB 

are legal, but: 

#X=FORLIB * ROOT 

is not. Unpredictable results will occur. 


6.7.1 User Library Searches 

Object modules from the named user libraries built by the Librarian 
ape relocated selectively and linked by the Linker. The RT—11 Linker 
searches a specified library file during the library pass as follows 
(refer to Figure 6-5 for a flowchart representation of this process): 

1. If there are any undefined globals in the Linker's table 
when a library is encountered in the command string, proceed 
to step 2; otherwise skip this library (go to step 5). 

2. Read the library directory. 

3. If any of the undefined globals can be defined by a module 
in this library, include the relevant module into the linked 
output file; otherwise, go to step 5. 

4 . if any undefined globals remain in the Linker's table and 
they have not been looked for in the library, return to step 
2; otherwise go to step 5. 

5. Close the library file. 

6. Go to the next element in the command string. 

This search method allows modules to appear in any order in the 
library. Any number of libraries may be specified in a link, and they 
may be positioned anywhere, with the exception of overlay segments and 
the restrictions noted in Section 6.7. 
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Figure 6-5 
Library Searches 


NOTE 

For faster Linker performance, the user 
should specify all object files before 
library files, and all user library 
files before the system library files. 
For example: 
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jfc A— A i B y US EL IB/F 

where A and B are object modules, USELIB 
is a user-created library file, and /F 
denotes the default FORTRAN library, 

FORLIB. 

Libraries are input to the Linker as any other input file. Assume the 
following command string to the Linker: 

* T ASKO1 ♦ 8AU ? LP t A 1 N <• OBJ ? ME ABU R ♦ OBJ 

This causes program MAIN*OBJ to be read from DK: as the first input 
file* Any undefined symbols generated by program MAIN.OBJ should be 
satisfied by the library file MEASUR.OBJ specified in the second input 
file. The load module, TASK01.SAV is put on DK: and a load map goes 
to the line printer. 


6.8 SWITCH DESCRIPTION 

The switches summarized in Table 6-1 are described in detail below. 


6.8.1 Alphabetize Switch 

The /A switch requests the Linker to list linked modules in 
alphabetical order as follows: .CSECTs, module names, and entry 
points within modules. The load map is normally arranged in order by 
module address as shown in Figure 6—1. Figure 6—6 is an example of an 
alphabetized load map for a background job. 


6.8.2 Bottom Address Switch 

The /B switch specifies the lowest address to be used by the 
relocatable code in the load module. When /B is not specified, the 
Linker positions the load module so that the lowest address is 
location 1000 (octal), or 0 for a foreground link. If the .ASECT 
length is greater than 1000, the length of .ASECT is used. 

The form of the bottom switch is: 

/B:n 

n is a six-digit unsigned octal number which defines the bottom 
address of the program being linked. An error message results if n is 
not specified as part of the /B command. 

If more than one /B switch is specified during the creation of a load 
module, the first /B switch specification is used. 


NOTE 

The bottom value must be an unsigned 
even octal number. If the value is odd, 
an error message is generated. 
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# 



RT-ll LINK V03-01 LOAD MAP 
SORT .5A V 19-3EP-74 


SECTION ADOft 

SIZE 

. ASS, 000000 

001000 

001000 

000220 

001000 

001364 

002604 

002300 

005104 

000160 

005264 

000102 


005366 

000020 

005406 

000046 

005454 

000062 

005536 

000036 

005574 

000174 

005770 

000026 

006016 

000044 



006062 

0fcj&)0 72 


006154 

000002 

SERRT8 

006156 

000100 

SERBS 

006256 

002637 


011116 

00153a 


012652 

000202 


013054 

000416 


013472 

000106 


013600 

000302 


014102 

000262 


014364 

000106 


014472 

000674 


015366 

000110 


015476 

000414 


016112 

000042 


ENTRY 

ADDR 

ENTRY 

SLRECL 

000210 

snlchn 

strace 

004737 

SV005A 

SOTI 

001246 


DCOS 

004164 

ECOS 

GC OS 

004144 

ICIS 

OCIS 

002604 

ocos 

SGET 

002772 


ISNS 

005104 

LSNS 

SLSNTH 

005130 


MQISIa 

005310 

MQISIM 

moisma 

005324 

MOISMM 

MOISSA 

005274 

MQISSM 

MOIS0A 

005340 

MOIS0M 

MOIS1A 

005360 

MOIS1M 

MOLSIS 

005300 

MOLSSS 

IFRS 

005366 

IFW$ 

EOLS 

005406 


T V DS 

005470 

T VPS 

TVLS 

005454 

T V PS 

C A I S 

005536 

CALS 

SORT 

005574 


mofsra 

006006 

MOPSRM 

MOF $RS 

005770 


6EQ5 

006036 

BGES 

6 L t S 

006034 

blts 

bRAS 

006050 

NMIS1I 

EXIT 

006074 

POOS 

SAOTS 

006154 



SFIO 

011600 


SFMTOR 

012652 

sfmtdn 

SCL08E 

013054 


LCIS 

013472 

LCOS 

SGETRE 

013600 

STTYIN 

SPUTRE 

014102 


SPtHNL 

014364 


SOPEN 

014472 


SOUMPL 

015366 


5E0FIL 

016046 

SGETBL 

SMIT 

016112 



ADOR 

ENTRY 

ADOR 

000006 

000001 

SUSRSW 

000000 

004156 

002612 

003712 

PCOS 

ICOS 

RC IS 

004152 

003720 

003006 

005124 

SI3NTK 

005110 

005304 

005320 

005270 

005334 

005352 

005264 

005400 

MOISIS 
MOISMS 
MOISSS 
MO I 80S 
MOISIS 
RELS 

005300 

005314 

005264 

005330 

005344 

005300 

005462 

005504 

005544 

TVIS 

T VOS 

005512 

005476 

005776 

MOP SRP 

006012 

006046 

006056 

006026 

006062 

BGTS 

BNES 

nmisim 

STPS 

006044 

006054 

006016 

006074 

012702 

SINITI 

012750 

013540 

013722 




015676 SPUTBL 015476 


TRANSFER ADDRESS » 001000 
HIGH LIMIT « 016154 

Figure 6-6 

Alphabetized Load Map for a Background Job 
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/B is illegal with foreground links. 
Example: 


ik 0 U T P U T»I... P i - 1N P U T / B 5 500 


(0 is assumed.) 


Causes the input file to be 
linked starting at location 
500 (octal). 


6.8.3 Continue Switch 

The Continue switch (/C) is used to allow additionaiiines of command 
string input. The /C switch is typed at the end of the current line 
and may be repeated on subsequent command lines as often as necessary 
to specify all input modules for which memory is available. If memory 
is exceeded, an error message is output. A /C switch is not entered 
on the last line of input. 


Example: 


*OUTPUTfLPJrINPUT/C 

* 


Input is to be continued on 
the next line; the Linker 
prints an asterisk. 


6.8.4 Default FORTRAN Library Switch 

By indicating the /F switch in the command line, the FORTRAN library, 
FORLIB.OBJ on the default device (SYs), is linked with the other 
object modules specified; the user does not need to specify FORLIB. 
For example: 

* FIL E > I... P t ~ A B ♦ 0 B J / F 

The object module AB.OBJ and the FORTRAN library FORLIB are linked 
together to form a load module called FILE.SAV. (Note that the FORLIB 
default is SY:FORLIB.OBJ, not DK:FORLIB.OBJ.) 

6.8.5 Include Switch 

The /I switch allows subsequent entry at the keyboard of global 
symbols to be taken from any library and included in the linking 
process. When the /I switch is specified, the Linker prints: 

LIBRARY SEARCH: 

Reply with the list of global symbols to be included in the load 
module; type a carriage return to enter each symbol in the list. A 
carriage return alone terminates the list of symbols. This provides a 
method for forcing modules (which are not called by other modules) to 
be loaded from the library. 

Example: 


* 0 U T P U T r L P: = IN PIJ T y X L I B /1 


LIBRARY search: Linker prints LIBRARY SEARCH: 


A <CR> 
GETSYM <CR> 
CHAR <CR> 
CHFLG <CR> 
<CR> 


User enters A, GETSYM, etc. which are 
to be included in the linking process. 
Each symbol is entered by typing 
a carriage return; the list is termi¬ 
nated by an additional carriage return. 
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6.8.6 LDA Format Switch 

The LDA format switch (/L) causes the output file to be in LDA format 
instead of save image format. The LDA format file can be output to any 
device, including devices that are not block-replaceable such as paper | 
tape or cassette, and is useful for files which are to be loaded with 
the Absolute Loader. The default extension .LDA is assigned when the 
/L switch is used. 

The /L switch cannot be used in conjunction with the overlay switch 
(/0) or in foreground links (/R). 

Example: 

* DK J OUT? LP5 - 1N yIN2/L 


6.8.7 Modify Stack Address 

The stack address, location 42, is 
user's stack pointer. The /M 
specification of the user's stack address. 

The form of the switch is: 

/M:n 

n is an even unsigned 6-digit octal number which defines the stack 
address. If n is not specified, the Linker prints the message: 

STACK ADDRESS = 

In this case, specify the global symbol whose value is the stack 
address. A number cannot be specified, and if a nonexistent symbol is 
specified, an error message is printed and the stack address is set to 
the system default (1000 for save files, 0 for REL). 

Direct assignment (via .ASECT) of the stack address within the program 
takes precedence over assignment with the /M switch. 

Example: 

*OUTPUT-INPUT/M 
STACK ADDRESS = BEG 


Links disk files IN and IN2; 
outputs an LDA format file 
OUT.LDA to the system device 
and a load map to the line 
printer. 


the address which contains the 
switch allows terminal keyboard 


6.8.8 Overlay Switch 

The Overlay switch (/O) is used to segment the load module so that the 
entire program is not memory resident at one time (overlay feature). 
This allows programs larger than the available memory to be executed. 
The switch has the form: 

/0:n 
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where n is an unsigned octal number (up to six digits in length) 
specifying the overlay region to which the module is assigned* The /0 
switch must follow (on the same line) the specification of the object 
modules to which it applies, and only one overlay region can be 
specified on a command line. Overlay regions cannot be specified on 
the first command line as this is the root segment. Therefore, the /C 
continuation switch must be used. 

Co-resident overlay routines (a group of subroutines which occupy the 
| overlay region and segment at the same time) are specified as follows: 

*0BJA,OBJB,OBJC/O:n/C 
*OBJD,OBJE/O:m/C 


All modules mentioned until the next /0 switch will be co-resident 
overlay routines. If at a later time the /0 switch is given with the 
same value previously used (same overlay region), then the 
corresponding overlay area is opened for a new group of subroutines. 
The new group of subroutines will occupy the same locations in memory 
as the first group, but not at the same time. For example, if 
subroutines in object modules R and S are to be in memory together, 
but are never needed at the same time as T, then the following 
commands to the Linker make R and S occupy the same memory as T (but 
at different times): 


* MAIN*LP• ~ R00T/C 

* R ?S/0 * 1/C 

* T/o t :i 

The above could also be written as: 

*hain>lp:=root/c 

#R/011/C 
*S/C 

*T/o: :l. 


Example: 

* output»lp:=input/c 

* OBJA/Ot l/C 

* 0BJB/052 

Overlays must be specified in order 
example: 


Establishes two overlay 
regions 

of increasing region number. For 


.R LINK 

*A-A/C 

*B/OU/C 

*c/o;l/c 

*d/o:i/c 

*E rF/052/C 
*0/0:3 

The following overlay specification is illegal since the overlay 
regions are given in a random numerical order (an error message is 
printed in each case): 


January 1976 
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t R LINK 
♦A*A/C 
*D/0 1 2/C 

*b/o: l/c 

/O IGNORED 
XtC/Oi 1/C 
/O IGNORED 
*G/0 J 3/C 
*H/0 i 3/C 
#E ?F/O;2 
,/0 IGNORED 


6.8.9 REL Format Switch 

The REL format switch (/R) causes the output file to be in REL format 
for use as a foreground job under the F/B Monitor. REL format files 
must be used in a foreground job (they may not be used under a 
Single-Job system). The /R switch assigns the default extension .REL 
to the output file. 

Example: 

<(DT2J FILED r LP • =FILEI ? NEXT/R Disk files FILEI and NEXT are 

linked and output to DT2 as 
FILEO.REL; a load map is 
output to the line printer. 

The /B and /L switches cannot be used with /R since a foreground REL 
job has no bottom address and is always relocated by FRUN. A ?BAD 
SWITCH? error message is generated if this is attempted. 


6.8.10 Symbol Table Switch 

Use of the symbol table switch in the command line instructs the 
Linker to allow the largest possible memory area for its symbol table 
at the expense of making the link process slower. With the /S switch, 
library directories are not made resident in memory, but cure left on 
disk. For example: 

*0UTF f LP2 = INPUT . OBJ , L IBRI . OBJ t LIBR2 . OBJ/S 

The directories of the library files LIBR1 and LIBR2 are not brought 
into memory, resulting in more room in the symbol table but longer 
link time. 

If the /S switch is not used and the memory available to the Linker is 
approximately 10K or larger, the library directory is brought into 
memory (providing there is room); the directory is kept there until 
the library has been completely processed, thus reducing the size of 
the Linker's symbol table. If there is not enough room in memory for 
the directory (as is the case in an 8K system), the Linker determines 
this and leaves the directory on disk regardless of whether the /S 
switch was used or not. 

The /S switch should be used only if an attempt to link a program 
failed because of symbol table overflow. Often, use of /S will allow 
the program to link. 
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6.8.11 Transfer Address Switch 

The transfer address is the address at which a program is to be 
started when executed via an R, RUN, or FRUN command. The Transfer 
Address switch (/T) allows terminal keyboard specification of the 
start address of the load module to be executed. This switch has the 
form: 


/T:n 

where n is a six-digit unsigned octal number which defines the 
transfer address. If n is not specified, the message: 

TRANSFER ADDRESS = 

is printed. In this case, specify the global symbol whose value is 
the transfer address of the load module, followed by a carriage 
return. A number cannot be specified in answer to this message. When 
a nonexistent symbol is specified, an error message is printed and the 
transfer address is set to 1 (so that the program cannot be executed). 

If the transfer address specified is odd, the program does not start 
after loading and control returns to the monitor. 

Direct assignment (.ASECT) of the transfer address within the program 
takes precedence over assignment with the /T switch. The transfer 
address assigned with a /T has precedence over that assigned with a 
.END assembly directive. 

Example: 

*PR0G=PR0G1»PR0G2>0DT/T The files PR0G1.0BJ,PR0G2.0BJ 

TRANSFER ADDRESS = and ODT.OBJ are linked to- 

O.gdt gether and started at ODT's 

transfer address. 


6.9 LINKER ERROR HANDLING AND MESSAGES 

The following error messages cam be output by the Linker. The 
messages enclosed in question marks are output to the terminal; the 
other messages are only warnings amd are included in the load map. If 
a load map is not requested in the commamd string, all messages aure 
output to the terminal. 

Message Meaning 


ADDITIVE REF OF xxxxxx Rule 1 of overlay rules explained in Section 

| AT SEGMENT # yyyyyy 6.6 has been violated, xxxxxx represents the 

entry point; yyyyyy represents the segment 
number. 

?/B NO VALUE? The /B switch requires an unsigned even 

octal number as an argument. 


?/B ODD VALUE? The argument to the /B switch was not an 

unsigned even octal number. 

?BAD GSD? There is an error in the global symbol 

directory (GSD). The file is probably not a 
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legal object module. This error message 
occurs on pass 1 of the Linker. 

BAD OVERLAY AT SEG # YYYYYY 

Overlay tries to store text outside its 



region; check for a .ASECT in overlay. 

YYYYYY represents the segment number. 

?BAD RLD? 

There is an invalid relocation directory 
(RLD) command in the injjut file; the file is 
probably not a legal object module. The 
message occurs on pass 2 of the Linker. 

?BAD SWITCH? 

LINK did not recognize a switch specified on 
the first command line. On a subsequent 
command line, a bad switch causes this 
warning message but does not restart the 
Linker. 

?BAD x SWITCH IGNORED? 

LINK did not recognize a switch (x) specified 
in the command line. The switch is ignored 
and linking continues. 


BYTE RELOCATION ERROR AT xxxxxx 



Linker attempted to relocate and link byte 
quantities but failed, xxxxxx represents the 
address at which the error occurred. Failure 
is defined as the high byte of the relocated 
value (or the linked value) not being all 
zero. In such a case, the value is truncated 
to 8 bits and the Linker continues processing 
(for save image and LDA files only; byte 
relocation is completely illegal for REL 
files). 

?CORE? 

There is not enough memory to accommodate the 
command or the resultant load module. 

?ERROR ERROR? 

An error occurred while the Linker was in the 
process of recovering from a previous system 
or user error. 

?ERROR IN FETCH? 

The device is not available. 

?FILE NOT FND? 

Input ^ile was not found. 

7FORLIB NOT FND? 

The user indicated via the /F switch that the 
FORTRAN library, FORLIB, was to be linked 
with the other object modules in the command 
line, and the Linker could not find 
FORLIB.OBJ on the system device. 

?HARD I/O ERROR? 

A hardware error occurred; try the operation 
again. 

?ILL ASECT? 

The user has attempted to place an .ASECT 
above 1000 in a foreground link or to place 
an .ASECT into an overlay foreground link. 
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?LDA FILE ERROR? There was a hardware problem with the device 

specified for LDA output or the device was 
full. 

?/M ODD VAL? An odd value has been specified for the stack 



address. Control returns to the Linker and 

smother command line may be indicated. 

?MAP FILE ERROR? 

There was a hardware problem with the device 
specified for map output or the device is 
full. 

* 

MULT DEF OF xxxxxx 

The symbol, xxxxxx, was defined more than 
once. 

?N0 INPUT? 

No input files were specified. 

/0 IGNORED 

Overlays have been specified in the wrong 
order (see overlay restrictions); the overlay 
switch is ignored. 

?OUTPUT FULL? 

The output device was full. 

?REL FILE ERR? 

The Linker encountered a problem writing the 
REL file; try the operation again. 

?SAV FILE ERR? 

The Linker encountered a problem writing the 
save image file; try the operation again. 


?STACK ADDRESS UNDEFINED OR IN OVERLAY? 



The stack address specified by the /M switch 
was either undefined or in an overlay. The 
stack address is set to the system default. 

?SYMBOL TABLE OVERFLOW? 

There were too many global symbols used in 
the program. Retry the link using the /S 
switch. If the error still occurs, the link 
cannot take place in the available memory. 

?T00 MANY OUTPUT FILES? 

The Linker allows specification of only two 
output files. 


TRANSFER ADDRESS UNDEFINED OR IN OVERLAY? 

The transfer address was not defined or was 


UNDEF GLBLS 

in an overlay. 

A load map was requested and undefined 
globals existed. 

UNDEFINED GLOBALS 

xxxxxx 

xxxxxx 

• 

. 

The globals listed (xxxxxx) were undefined. 

If a load map is requested, this condition 
also causes the warning message, UNDEF GLBLS, 
to be printed on the terminal. 
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FORTRAN "BLOCK DATA" INITIALIZATIONS ARE INCORRECT WHEN LINKED TO A FORTRAN PROGRAM 
FROM A LIBRARY (SPR 11-9062, 11-9467 MS) 


FORTRAN "BLOCK DATA" initializations are incorrect when linked to a FORTRAN program 
from a library. 

Object modules containing BLOCK DATA subprograms should not be placed in a library. 
If, however, it is absolutely necessary to include a BLOCK DATA subprogram in a 
library, either of the following methods will obviate the problem. 

1. Use the construction 

BLOCK DATA NAME 

Compile the module and insert it into the library (called BLKDAT in 
this example.) NAME will then be a global symbol which can be 
included in the link by specifying the /I switch in the linker 
command line, specifying NAME when queried. Viz., 

.R LINK <CR> 

*mainc,mapo=main,blkdat/f/i <CR> 

LIBRARY SEARCH: 

NAME <CR> 

<CR> 

UNDEF GLBLS 
*C 


2. Alternatively, if NAME (Item 1) is omitted from the BLOCK DATA 
statement, then the symbol which must be included is .DATA, which is 
the default name given to unnamed BLOCK DATA subprogram by the 
FORTRAN compiler. Viz., 

.R LINK <CR> 

*MAINC/MAP:1=MAIN,BLKDAT/F/I <CR> 

LIBRARY SEARCH: 

.DATA. <CR> 

<CR> 

UNDEF GLBLS 
*C 


In each case, the UNDEF GLBLS message will be printed, and can be 
ignored, although the map (or map file) will be highly desirable to insure 
that NAME or .DATA. , depending upon the case, is the only undefined 
symbol. 


\ 
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PERFORMANCE IMPROVEMENT IN LINKER 


An enhancement can be made to the linker which will improve the 
execution time when linking with libraries. The most dramatic 
change in linking time will be noticed when using a slower CPU 
(e.g., 11/05 or 11/10). The following patch is to LINK V04-04. 


.R PATCH <CR> 

PATCH V01-02 

FILE NAME — 

★LINK.SAV <CR> 

*616/ 1043 1077 <CR> 

*E 

.R PATCH <CR> 

PATCH V01-02 

FILE NAME-- 
*LINK.SAV/0 <CR> 

7B0TT0M ADDR WRONG? 

*500;B 


*3242/ 

12700 

105767 <LF> 

3244/ 

1636 

176531 <LF> 

3246/ 

10146 

1404 

<LF> 

3250/ 

10003 

167 <LF> 

3252/ 

12702 

6040 

<LF> 

3254/ 

10 

62704 

<LF> 

3256/ 

112420 

10 <LF> 

3260/ 

105767 

11400 

<LF> 

3262/ 

176513 

1416 

<LF> 

3264/ 

1412 

21100 

<LF> 

3266/ 

20405 

1372 

<LF> 

3270/ 

103410 

2bl64 

<LF> 

3272/ 

10046 

2 <LF> 

3274/ 

105067 

2 <LF> 

3276/ 

176475 

1366 

<LF> 

3300/ 

4767 

12703 

<LF> 

3302/ 

1054 

1636 

<LF> 

3304/ 

12600 

10300 

<LF> 

3306/ 

105167 

12420 

<LF> 
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3310/ 176463 

12420 

<LF> 

3312/ 5302 

12420 

<LF> 

3314/ 1360 

12420 

<LF> 

3316/ 10300 

207 

<LF> 

3320/ 5202 

261 

<LF> 

3322/ 22123 

207 

<CR> 

*7210;OR 




*2:0,2104/ 

XXX 


12702 <LF> 

2 

0,2106/ 

XXX 


4 <LF> 

2 

0,2110/ 

XXX 


12703 <LF> 

2 

0,2112/ 

XXX 


1636 <LF> 

2 

0,2114/ 

XXX 


5714 <LF> 

2 

0,2116/ 

XXX 


1424 <LF> 

2 

0,2120/ 

XXX 


20405 <LF> 

2 

0,2122/ 

XXX 


103406 <LF> 

2 

0,2124/ 

XXX 


105067 <LF> 

2 

0,2126/ 

XXX 


170435 <LF> 

2 

0,2130/ 

XXX 


4767 <LF> 

2 

0,2132/ 

XXX 


173014 <LF> 

2 

0,2134/ 

XXX 


105167 <LF> 

2 

0,2136/ 

XXX 


170425 <LF> 

2 

0,2140/ 

XXX 


12423 <LF> 

2 

0,2142/ 

XXX 


5302 <LF> 

2 

0,2144/ 

XXX 


1365 <LF> 

2 

0,2146/ 

XXX 


12703 <LF> 

2 

0,2150/ 

XXX 


1636 <LF> 

2 

0,2152/ 

XXX 


21113 <LF> 

2 

0,2154/ 

XXX 


1353 <LF> 

2 

0,2156/ 

XXX 


26163 <LF> 

2 

0,2160/ 

XXX 


2 <LF> 

2 

0,2162/ 

XXX 


2 <LF> 

2 

0,2164/ 

XXX 


1347 <LF> 

2 

0,2166/ 

XXX 


207 <LF> 

2 

0,2170/ 

XXX 


261 <LF> 

2 

0,2172/ 

XXX 


207 <CR> 

*7216;OR 




*4:0,24\ 

40 


101 <CR> 


The new LINK version will be LINK V04-04A. 

Note: The 7B0T0M ADDR WRONG? error is produced for the following 
reason. Patch expects LINK to be loaded at location 1000 
(default), but Is actually loaded starting in location 500. LINK*s 
true base address must be set to its actual value (500;B). 
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CHAPTER 7 


LIBRARIAN 


The RT-11 system provides the user with the capability of maintaining 
libraries which may be composed of functions and routines of his 
choice. Each library is a file containing a library header, library 
directory (or entry point table), and one or more object modules. The 
object modules in a library file may be routines which are repeatedly 
used in a program, routines which are used by more than one program, 
or routines which are related and simply gathered together for ease in 
usage—the contents of the library file are determined by the user's 
needs. An example of a typical library file is the FORTRAN library, 
FORLIB•OBJ. This library is provided with the FORTRAN package and 
contains all the mathematical functions needed for normal usage. 

Object modules in a library file are accessed from another program via 
calls to their entry points; the object modules are linked with the 
program which uses them by the Linker (Chapter 6) to produce a single 
load module. 

The RT-11 Librarian (LIBR) allows the user to create, update, modify, 
list, and maintain library files. 


7.1 CALLING AND USING LIBR 

The RT-11 Librarian is called from the system device by entering the 
command: 

R LIBR 

in response to the dot printed by the Keyboard Monitor. The Command 
String Interpreter prints an asterisk at the left margin on the 
console terminal when it is ready to accept a command line. 

Type CTRL C to halt the Librarian at any time and return control to 
the monitor. To restart the Librarian, type R LIBR or the REENTER 
command in response to the monitor's dot. 


7-1 




Librarian 


7.2 USER SWITCH COMMANDS AND FUNCTIONS 

The user maintains library files through the use of switch commands. 
Functions which can be performed include object module deletion, 
insertion and replacement, library file creation, and listing of a 
library file's contents. 


7.2.1 Command Syntax 

LIBR accepts command strings in the following general format: 
*dev:lib,dev:list=dev:input/s1/s2/s3 


where: 


dev: 

lib 

list 


represents a legal RT-11 device specification 

represents the library file to be created or 
updated 

represents a listing file for the library's 
contents 


input represents the filenames of the input object 

modules 

/si,... represents one or more of the switches listed 

in Table 7-1 


Devices and filenames are specified by the user in the standard RT-11 
command string syntax, with default extensions assigned as follows: 


File 


Extension 


list file: 
library file: 
input files: 


• LLD 
.OBJ 
.OBJ 


If no device is specified, the default device (DK:) is assumed. 


Each input file is made up of one or more object modules, and is 
stored on a given device under a specific filename and extension. 
Once an object module has been inserted into a library file, the 
module is no longer referenced by the name of the file of which it was 
a part, but by its individual module name. (This module name has been 
assigned by the assembler either via a .TITLE statement in the 
assembly source program, or, if no .TITLE statement is present, with 
the default name .MAIN.; see Chapter 5.) Thus, for example, the input 
file FORT.OBJ may exist on DT2: and may contain an object module 
called ABC. Once the module is inserted into a library file, 
reference is made only to ABC (not FORT.OBJ). 


7.2.2 LIBR Switch Commands 

Table 7-1 summarizes the switches available for use under RT-11 LIBR. 
Switches are explained in detail following the table. 
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Table 7-1 
LIBR Switches 



There is no switch to indicate module insertion. The function of 
inserting a module into a library file is assumed in the absence of 
other switches. 


7.2.2.1 Command Continuation Switch - The Command Continuation switch 
is necessary whenever there is not enough room to enter a command 
stri **9 on one lme and additional lines are needed. The /C switch is 
typed at the end of the current line and may be repeated at the end of 
subsequent command lines as often as necessary as long as memory is 
available; if memory is exceeded, an error message is output. A /C 
switch is not entered on the last line of input. 

Command Formats 


*dev:lib,dev:list=dev:input1,devsinput2,... ,/C 
*dev:inputn 


where: 


dev: represents a device specification 

■Lib lapissents the filename of the library to be 
created or updated 

list represents the filename of a listing file containing 
the library file's contents 

input represents the filenames of the input modules to be 
inserted into the library 

/C represents the Continuation switch, indicating 

that the command is to be continued on the following 
line 3 
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Examples s 


* A L 1 B y LIB L B T«D T1 l MA 1 N y T E S T y F X N / C 
#DT1 ** TRACK 

In this example, a library file is created on the default device (DK:) 
under the filename ALIB.OBJ; a listing of the library filers contents 
is created as LIBLST.LLD also on the default device; the filenames of 
the input modules are MAIN.OBJ, TEST.OBJ, FXN.OBJ, and TRACK.OBJ, all 
from DTI. 


#BLIB-MAIN/C 
*RK11 TEST/C 
*RKO:FXN/C 
#DT1J TRACK 

A library file is created on the default device, (DK:) under the name 
BLIB. No listing is produced. Input files are MAIN from the default 
device, TEST from RK1:, FXN from KKO: and TRACK from DTI. 

Another way of writing this command line is: 

* B LIB=M AIN y R K :L i T E S T y R K 0 l F X N / C 
*DT1JTRACK 


7.2.2.2 Creating a Library File - A library file is created whenever 
a filename is indicated on the output side of a command line which 
does not represent a list file. 

Command Format: 

*dev:lib=dev:input1,...,dev:inputn 

where: 

dev: represents a device specification 

lib represents the filename of the library to be created 

input represents the filenames of the input modules to be 

inserted into the new library 

Example: 


* N E W LIB=FIR S T y S E C 0 N D 

A new library called NEWLIB.OBJ is created on the default device 
(DK:). The modules which will make up this library file are in the 
files FIRST.OBJ and SECOND.OBJ, both on the default device. 

Assume this command line is next entered: 

*NEWL..IB y I...IST-TH 1 RD y FOURTH 

The already existing library file NEWLIB is destroyed when the new 
library file is created. A listing of the library filers contents is 
created under the filename LIST, and the object modules in the files 
THIRD and FOURTH cure inserted into the library file NEWLIB. 
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7.2.2.3 Inserting Modules Into a Library - The Insert function is 
assumed whenever an input file does not have an associated switch; 
the modules in the file are inserted into the library file named on 
the output side of the command string. Any number of input files are 
allowed. If an attempt is made to insert a file which contains an 
entry point or .CSECT having the same name as an entry point or .CSECT 
already existing in the library file, a warning message is printed. 
However, the library file is updated, ignoring the entry point or 
.CSECT in error, and control returns to the CSI; the user may enter 
another command string. 

Although the user may insert object modules which exist under the same 
name (as assigned by the .TITLE statement) this practice is not 
recommended because of the difficulty involved when replacing or 
updating these modules (refer to Sections 7.2.2.4 and 7.2.2.7). 

NOTE 

The library operations of module 
insertion , replacement , deletion , merge , 
and update are actually performed in 
conjunction with the library file 
creation operation. Therefore , the 
library file to which the operation is 
directed must be indicated on both the 
input and output sides of the command 
line, since effectively a "new" output 
library file is created each time the 
operation is performed. The library 
file must be specified first in the 
input field. 

Command Format; 

*dev:lib=dev:lib,dev:inputl,.•.,dev:inputn 

where: 

dev: represents a device specification 

lib represents the filename of an existing library 

file 

input represents the filenames of the modules to be 

inserted into the library file 

Example: 

* D X Y ••••:•• n X Y y D T1 : F A y F B y F C 

The modules included in the files FA.OBJ, FB.OBJ, and FC.OBJ on DTI: 
are inserted into a library file named DXY.OBJ on the default device. 
The library header and Entry Point Table of the library file are 
updated accordingly (see Section 7.4). 


7,2.2.4 Replace Switch - The Replace function is used to replace 
modules in a library file. All modules contained in the file(s) 
indicated as input will replace existing modules of the same names in 
the library file specified as output. 
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An error message is printed and no modules are replaced if an old 
module does not exist under the same name as an input module, or if 
the user specifies the /R switch on a library file. /R must follow 
each input filename containing modules for replacement. 

Command Formats 

*dev:lib=dev: lib,inputl/R,...,dev:inputn/R 

where: 


dev: 

represents 

a device specification 

lib 

represents 

file 

the filename of an 

existing library 

input 

represents 
modules to 

the names of the 
be replaced 

files containing 

/R 

represents 

the Replace switch 



Examples: 


*TFIL=TFIL»INA>INB/R»INC 

This command line indicates that the modules in the file INB.OBJ are 
to replace existing modules of the same names in the library file 
TFIL.OBJ. The object modules in the files INA.OBJ and INC.OBJ are to 
be added. All files are stored on the default device DKs. 

*XFI L-TF IL »INA» INB./R * INC 

The same operation occurs here as in the preceding example, except 
that this updated library file is assigned the new name XFIL. 


7.2.2.5 Delete Switch - The Delete switch deletes modules and all 
their associated entry points from the library. 

Command Formats 

*dev slib=dev slib/D 

where: 


dev: 

represents 

exists 

the 

device on 

which the library 

file 

lib 

represents 

file 

the 

filename of an existing library 

/D 

represents 

the 

Delete 

switch; may 

be 


positioned 

anywhere on 

the input side of 

the 


command line 




When the /D switch is used, the Librarian prints: 
MOD NAME: 
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The u ser should respond with the name of the module to be deleted 
followed by a carriage return; he may continue until all modules to 
be deleted have been entered. Typing only a carriage return (either 
on a line by itself or immediately after the MOD NAME: message) 
terminates input and initiates execution of the command line. 

Examples: 


*DT3:TRAP=DT3J TRAP/D 


MOD name: 

SON <CR> 

TAN <CR> 

<CR> 

The modules SGN.OBJ and TAN.OBJ are deleted from the library file 
TRAP.OBJ on DT3j. * 


*LIBFIL=LIBFIL/D»ABC/R>DEF 


MOD name: 

FIRST <CR> 

<CR> 

The module FIRST.OBJ is deleted from the library (LIBFIL); the module 
ABC.OBJ replaces an old module of the same name in the library, and 
the modules in the file DEF.OBJ are inserted into the library. 

*LIBFIL=LIBFIL/D 


MOD name: 

X <CR> 

X <CR> 

<CR> 

Two modules of the same name are deleted from the library file LIBFIL 
(module names are assigned with the .TITLE statement as described in 
Section 7.2.1). 


7.2.2.6 Delete Global Switch - The Delete Global switch gives the 
user the ability to delete a specific entry point from a library 
file's Entry Point Table. 

Command Format: 

*dev:lib=dev:lib/G 


where: 


dev: 

represents 


exists 

lib 

represents 


file 


the device on which the library file 
the filename of an existing library 
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represents the Delete Global switch; may be 
positioned anywhere on the input side of the 
command line 


When the /G switch is used, the Librarian prints: 
ENTRY POINT: 


The user should respond with the name of the entry point to be deleted 
followed by a carriage return; he may continue until all entry points 
to be deleted have been entered. Typing only a carriage return 
(either on a line by itself or immediately after the ENTRY POINT: 
message) terminates input and initiates execution of the command line. 

Example: 

♦ROLL^ROLL/G 



ENTRY POINT i 
NAMEA <CR> 
NAMEB <CR> 
<CR> 


This command instructs LIBR to delete the entry points NAMEA and NAMEB 
from the entry point table found in the library file ROLL.OBJ on DK:. 



Since entry points are only deleted from the Entry Point Table (and 
not from the library itself) whenever a library file is updated, all 
entry points that were previously deleted are restored unless the /G 
switch is again used to delete them. This feature allows the user to 
recover from inadvertently deleting the wrong entry point. 
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7 .2.2.7 Update Switch - The Update switch allows the user to update a 
library file by combining the insert and replace functions. If the 
object modules included in an input file in the command line already 
exist in the library file, they are replaced; if not, they are 
inserted, (No error messages are printed when using the Update 
function as might occur under the Insert and Replace functions,) /U 
must follow each input file containing modules to be updated. 

Command Formats 

*dev:lib=dev:lib,dev:inputl/U,••.,dev:inputn/U 
where: 


dev: 

represents 

lib 

represents 


file 

input 

represents 


modules to 

/U 

represents 


a device specification 

the filename of an existing library 

the names of files containing object 
be updated, 

the Update switch 


Examples s 


*B ALIB-BALIBfFOLT/UfTALfBART/U 

This command line instructs LIBR to update the library file BALIB,OBJ 
on the default device. First the modules in FOLT.OBJ and BART.OBJ 
replace old modules of the same names in the library file, or if none 
already exist under their names, the modules are inserted. Then the 
modules from the file TAL.OBJ are inserted; an error message is 
printed if the name of the module in TAL.OBJ already exists. 

*XLIB«XLIB/DfZ/U/G 

mod name: 

X <CR> 
x <CR> 

<CR> 

ENTRY POINT: 

SEC <CR> 

SEC1 <CR> 

<CR> 

There are two object modules of the same name (X) in both Z and 
XLIB? these are first deleted from XLIB. This ensures that both 

modules X in file Z are correctly placed into the library. Entry 
points SEC and SEC1 are also deleted from the Entry Point Table, 
but automatically return when the libary (XLIB) is updated. 


7.2.2 .8 Listing the Directory of a Library File - The user may 
specify that a listing of the contents of a library file be output by 
indicating both the library file and a list file in the command line. 
Since a library file is not being created or updated, it is not 
necessary to indicate the filename on the output side of the command 
line; however a comma must be used to designate a null output library 
file. 
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Command Formats: 

*,LP:=dev:lib 

or 

*,dev:list=dev:lib 

where: 

dev: represents a device specification 

lib represents the file name of an existing library file 

LP: indicates the listing is to be sent directly to the 

line printer 

list represents a list file of the library file's contents 

Examples: 


*»riT2 5LIST=LIBFIL 

This command line outputs to DECtape 2 as LIST.LLD a listing of the 
contents of the library file LIBFIL.OBJ on the default device. 

*rLPi=FLIB 

This command outputs on the line printer a listing of all modules in 
the library file FLIB.OBJ stored on the default device. Assuming this 
library is composed of modules STOP, WAIT, and IMUL, is 2 blocks long, 
was created on September 6, 1974, and the listing was requested on 
September 6, 1974, the directory format appears as follows: 


RT-tl LIBRARIAN 

X02-05 

S-SEP-74 


PL 18 

6-SER.74 

2 SLOCKS 


MODULE 

ENTRY/CSECT 

ENTRY/CSECT 

ENTRY/CSECT 

STOP 

STPS 



WAIT 

SwAIT 



IMUL 

MUISIS 

MUISMS 

MUISPS 


Hyisss 

SMLI 



7.2.2.9 Merging Library Files - Two or more library files may be 
merged under one filename by indicating all the library files to be 
merged in a single command line. The individual library files are not 
deleted following the merge. 

Command Format: 

*dev:1ib=dev:input1,...,dev:inputn 


where: 

‘levs represents a device specification 

lib represents the name of the library file which will 

contain all the merged files (if a library file 
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already exists under this name, it must also be 
indicated in the input side of the command line in 
order to be included in the merge) 

in P ut represents the library files to be merged together 
Thus, the command: 

*MAIN =M A I N t l R I G t S T F : ' > BAG 

combines library files MAIN.OBJ, TRIG.OBJ, STP.OBJ,,and BAC.OBJ under 
the existing library file name MAIN.OBJ; all files are on the default 
device DK:. 


* FORT :::: A >B,C 

This command creates a library file named FORT.OBJ and merges existing 
library files A.OBJ, B.OBJ, and C.OBJ under the filename FORT.OBJ. 

NOTE 

Library files that have been combined 
under PIP are illegal as input to both 
the Librarian and the Linker. 


7.3 COMBINING LIBRARY SWITCH FUNCTIONS 

Two or more library functions may be requested in the same command 
line. The Librarian performs functions in the following order: 

1. /C 

2. /D 

3. /G 

4. /U 

5. /R 

6 . Insertions 

7. Listing 

Example: 

*FIL..E, LP: =FILE/D, MODX > MODY/R 


MOD name: 

XYZ <CR> 

A<CR> 

<CR> 

Functions in this example are performed in order, as follows: 

1. Delete modules XYZ.OBJ and A.OBJ from the library file 
FILE.OBJ 

2. Replace any duplicate of the module in the file MODY.OBJ 

3. Insert the modules in the file MODX.OBJ 

4. List the contents of FILE.OBJ on the line printer 
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7.4 FORMAT OF LIBRARY FILES 

A library file is a contiguous file consisting of a header, an Entry 
Point Table (library directory) and one or more library object 
modules, as illustrated in Figure 7-1: 


LIBRARY HEADER 


ENTRY POINT TABLE 


OBJECT MODULES 


LIBRARY END TRAILER BLOCK 


Figure 7-1 

General Library File Format 


The following paragraphs describe in detail each component of a 
library file. 


7.4.1 Library Header 

The header section of a library file contains 17 (decimal) words which 
describe the current status of the file (refer to Figure 7-2). This 
includes information relating to the version of the Librarian in use, 
the date and time of file creation or update, the relative starting 
address of the Entry Point Table (EPT), the number of EPT entries 
available and in use, and the placing of the next module to be 
inserted into the library file. The contents of the library header 
are updated as the library file is modified, so that LIBR can always 
quickly and easily access the information it needs to perform its 
functions. Figure 7-2 illustrates the header format. 
















Librarian 



Figure 7-2 

Library Header Format 


7.4.2 Entry Point Table (Library Directory) 

The Entry Point Table is located immediately after the library header. 
It is composed of four-word entries which include the names, 
addresses, and entry points of all object modules in the library file. 
The first two words of an entry in the EPT contain the Radix 50 name 
by which an entry point, CSECT, or module is referenced. The third 
word provides a pointer to the object module where an entry point is 
defined. The fourth word contains the total number of CSECTs in the 
object module (information needed by the Linker), and the relative 
byte within the block pointing to the object module's starting point, 
as shown in Figure 7-3. 


0 

SYMBOL (RAD 50) 

2 

SYMBOL (RAD 50) 

4 


ADDRESS OF BLOCK 

6 

# OF CSECTS IN 
OBJECT MODULE 

RELATIVE BYTE IN BLOCK 


BIT 15= 1-MODULE NAME 

= 0r-CSECT OR ENTRY POINT NAME 
RELATIVE BYTE MAXIMUM=777g 
CSECTS MAXIMUM =177g 


I 


Figure 7-3 

Format of Entry Point Table 
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7.4.3 Object Modules 

Object modules follow the Entry Point Table. An object module 
consists of three main types of data blocks: a global symbol 
directory, text blocks, and a relocation directory. The information 
contained in these data blocks is used by the Linker during creation 
of a load module. 


7.4.4 Library End Trailer 

Following all object modules in a library file is a specially coded 
library end trailer which signifies the end of the file. This trailer 
is illustrated in Figure 7-4. 



FORMATTED BINARY HEADER 
FORMATTED BINARY LENGTH 
TYPE CODE 

NOT USED (MUST BE ZERO) 
CHECKSUM BYTE 


Figure 7-4 
Library End Trailer 

7.5 LIBR ERROR MESSAGES 

The following error messages are printed following incorrect use of 
LIBR; if any errors result during library processing , the user must 
reenter the command. 


Message 
?BAD LIBR? 


?BAD OBJ? 

?CSECT ERROR? 


Meaning 


The user has attempted to 
library file containing no 
entries or he has given an 
constructed library file 
Librarian as input. 


build a 
directory 
illegally 
to the 


A bad object module was detected during 
input. 


The user has extended beyond the 
allowable .CSECT space for an object 
module to be placed in the library 
(i.e., the object module contains 
greater than 127(decimal) .CSECTs). 
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Message Meaning 


?DEV FULL? 

The device is full; LIBR is unable to 
create or update the indicated library 
file. The CSI prints an asterisk and 
waits for the user to enter another 
command line. 

?FIL NOT FND? 

One of the input files indicated in the 
command line was not found. The CSI 
prints an asterisk; the command may be 
reentered. 

PILL CMD? 

An illegal command was used in the 
command line. The CSI prints an 
asterisk; the command may be reentered. 

xxxxxx ILL DEL 

An attempt was made to delete from the 
library* s directory a module or an entry 
point that does not exist; xxxxxx 
represents the module or entry point 
name. The name is ignored and processing 
continues. 

PILL DEV? 

An illegal device was specified in the 
command line. The CSI prints an 
asterisk; the command may be reentered. 

xxxxxx ILL INS 

An attempt was made to insert a module 
into a library which contains the same 
entry point as an existing module, 
xxxxxx represents the entry point name. 
The entry point is ignored but the module 
is still inserted into the library. 

xxxxxx ILL REPL 

An attempt was made to replace in the 
library file a module which does not 
already exist. xxxxxx represents the 
module name. The module is ignored and 
the library is built without it. 

PIN ERR? 

An unrecoverable hardware/software error 
has occurred while processing an input 
file. The CSI prints an asterisk and 
waits for another command to be entered. 

PLIBR FIL ILL REPL? 

The user has specified that a library 
file be replaced by another library 
file. Only object modules can be 
replaced. 

?NO CORE? 

Available free memory has been used up. 
The current command is aborted and the 
CSI prints an asterisk; a new command 
may be entered. 

POUT ERR? 

An unrecoverable hardware/software error 

has occurred while processing an output 
file. This may indicate that there is 
not enough space left on the device to 
create the library file, even though 
there may be enough directory entries. 
The CSI prints an asterisk and waits for 
the user to enter another command. 
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CHAPTER 8 


ON-LINE DEBUGGING TECHNIQUE 


^ T ""i\. 0n_ ^* ne Debu 9ging Technique (ODT) is a system program that aids 
in debugging assembled and linked object programs. From the keyboard, 
the user interacts with ODT and the object program to: 

1. Print the contents of any location for examination or 
alteration. 


2 ‘ breakpoint feature?^' 00 ° f “ ° bje ° t pr ° 9ri “» 


3. Search the object program for specific bit patterns. 

4. Search the object program for words which reference a 
specific word. 

5. Calculate offsets for relative addresses. 


6 . Fill a single word, block of words, byte or 
with a designated value. 


block of bytes 


°? tbe program to be debugged should be readily 
cln hfiL hen r 0DT ^ being used * Minor corrections to the program 
^h2n b k d on-line during the debugging session, and the progrin may 

cirLS n n a rUn >, r ° 0nt * 01 of 0DT to verify any changes made. Majoi: 
corrections, however (such as a missing subroutine), should be noted 

program in9 " d inc “P»« ted in « subsequent updated 


8.1 CALLING AND USING ODT 

ODT is supplied as a relocatable object module, it can be linked with 
the user program (using the RT-11 Linker) for an absolute area in 

memory and loaded with the user program. When linked with the user 

modate m its D st!ck? ld reSide in loW memor y^ starting at 1000, to accom- 

in memory with the user program, ODT has three legal start 
or restart addresses. The lowest (O.ODT) is used for normal entry, 
retaining the current breakpoints. The next (O.ODT+2) is a restart 
oenpral which dears ail breakpoints and re-initializes ODT saving the 
generai registers and clearing the relocation registers. The last 
address (O.ODT+4) is used to reenter ODT. A reenter saves the 
rocessor Status and general registers and removes the breakpoint 
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£ na p r nroaram. ODT prints the Bad Entry (BE) 

instructions breakpoints which were set are reset on the next jG 
error message. Breakpo t h BE ^ e#) The ;G ^ ;P commands 

“fused toi*p£S£ and »e explained in Section 8.3.7. 


The absolute address used is the 
shown in the Linker load map. 
ODT+172, i.e., O.ODT is relative 


address of the entry point O.ODT 
O.ODT is always the lowest address of 
location 172 in ODT. 


NOTE 

If linked with an overlay structured 
file, ODT should reside in the root 
segment so it is always in memory. A 
breakpoint inserted in an overlay will 
be destroyed if it is overlaid during 
program execution. 


If ODT is being used in a Foreground/Background environment with 
another job running, ODT's priority bit must be set to 0 as follows: 

* $ F' / 0 0 0 0 0 7 0 <CR> 

This puts ODT into the wait state at level 0, not 7. If is not 

done, all interrupts (including clock) will be locked out while ODT is 
waiting for terminal input. 


Examples: 

1. ODT Linked with the User Program: 

.GET USER. SRV User program previously linked to 

ODT is brought into memory. 

. STFIRT 1172 value (1172) of entry point O.ODT 

(determined from Linker load map) 
OPT V01-01 i s use d to start ODT. 

* 

2. Loading ODT with the User Program: 


GET 

0 D 7. S n V 

GET 

USER. 3ft 

STrif 

\ T 4Q17 2 

GDT 

V 31~ 0 &! 


ODT is loaded into memory. 

User program is loaded into memory. 

Assuming ODT has been linked for a 
bottom address of 40000, ODT starts. 


3. 


Restarting ODT Clearing Breakpoints: 


l STRRT 1174 
* 


Assuming ODT was originally 
linked for a bottom address of 1000, 
this command (O.ODT+2) 
re-initializes ODT and clears any 
previous breakpoints. 
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4. Reentering ODTs 

. START 1176 

BE691212 

•+ 


Assuming ODT was linked for a 
bottom address of 1000, the value 
of O.ODT 1172+4 is used as the 
start address. 


5. Using ODT with Foreground/Background Jobs: 

It is possible to use ODT to debug programs written as either 
background or foreground jobs. In the background or under 
the Single-Job Monitor, ODT can be linked with the program as 
described in Example 1 above. 

To debug a program in the foreground area, it is recommended 
that ODT be run in the background while the program to be 
debugged is in the foreground. The sequence of commands to 
do this is: 


^FRUN PROG /P 
LORDED ftT xxxxxx 

^ RUN ODT 

OPT V 01 — 01 
*XXXXXX;0R 
* $ F/006606 0<CR> 
*0; G 

. RSU 


Load the foreground program. 

The first address of the job is 
printed (xxxxxx) 

Run ODT in the background 
and set a relocation register 
to the start of the job. $F 
is the format register. It 
should be cleared to enable proper 
address print out. 0;G starts the 
Keyboard Monitor again, and .RSU 
starts the foreground job. 


The copy of ODT used must be linked low enough so that it 
will fit in memory along with the foreground job. 


NOTE 

Since ODT uses its own terminal handler, 
it cannot be used with the display 
hardware. If GT ON has been typed, ODT 
will ignore it and direct I/O only to 
the console terminal. 


8.1.1 Return to Monitor, CTRL C 

If ODT is awaiting a command, a CTRL C from the keyboard calls the 
RT-11 Keyboard Monitor. The monitor responds with a tC on the 
terminal and awaits a Keyboard Monitor command. (The monitor REENTER 
command may be used to reenter ODT only if the user program has set 
the reenter bit. Otherwise ODT is reentered at address O.ODT+4 as 
shown above.) 
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8.1.2 Terminate Search, CTRL U 

If typed during a search printout, a C XL U terminates the search and 
ODT prints an asterisk. 


8.2 RELOCATION 

When the assembler produces a binary object module, the base address 
of the module is taken to be location 000000, and the addresses of all 
program locations as shown in the assembly listing. are indicated 
relative to this base address. After the module is linked by the 
Linker, many values within the program, and all the addresses of 
locations in the program, will be incremented by a constant whose 
value is the actual absolute base address of the module after it has 
been relocated. This constant is called the relocation bias for the 
module. Since a linked program may contain several relocated modules 
each with its own relocation bias, and since, in the process of 
debugging, these biases will have to be subtracted from absolute 
addresses continually in order to relate relocated code to assembly 
listings, RT-11 ODT provides an automatic relocation facility. 

The basis of the relocation facility lies in eight relocation 
registers, numbered 0 through 7, which may be set to the values of the 
relocation biases at different times during debugging. Relocation 
biases should be obtained by consulting the memory map produced by the 
Linker. Once set, a relocation register is used by ODT to relate 
relocatable code to relocated code. For more information on the exact 
nature of the relocation process, consult Chapter 6, the RT-11 Linker. 


8.2.1 Relocatable Expressions 

A relocatable expression is evaluated by ODT as a 16—bit (6—digit 
octal) number and may be typed in any one of the three forms presented 
in Table 8-1. In this table, the symbol n stands for an integer in the 
range 0 to 7 inclusive, and the symbol k stands for an octal number up 
to six digits long, with a maximum value of 177777. If more than six 
digits are typed, ODT takes the last six digits, truncated to the 
low-order 16 bits, k may be preceded by a minus sign, in which case 
its value is the two's complement of the number typed. For example: 


k (number typed) 


Values 


1 

-1 

400 

-177730 

1234567 


000001 

177777 

000400 

000050 

034567 
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Table 8-1 



Forms of Relocatable Expressions (r) 


r 

Value of r 

A) 

k 

The value of r is simply the value of k. 

B) 

n,k 

The value of r is the value of k plus 
con ^ en ^ s of relocation register n. 

If the n part of this expression is 
greater than 7, ODT uses only the last 
octal digit of n. 

C) 

C or 

C,k or 
n,C or 
C,C 

Whenever the letter C is typed. ODT 
replaces C with the contents of a 
special register called the Constant 
Register. This value has the same role 
as the k or n that it replaces (i.e., 
when used in place 02 n it designates a 
relocation register). The Constant 
Register is designated by the symbol $C 
and may be set to any value, as 
indicated below. 


register 

000003. 


examples, 
contains 003400 


assume in each case that relocation 
ana that the constant register contains 


5;C 

-17;C 

3,0;C 

3,150;C 

3,-l;C 

C;C 

3,C;C 

C,0;C 

C,10;C 

C»C;C 


Value of r 

000005 

177761 

003400 

003550 

003377 

000003 

003403 

003400 

003410 

003403 


NOTE 


8.3 


For simplicity most examples in this 
section use Form A. All three forms of r 
are equally acceptable, however. 

COMMANDS AND FUNCTIONS 


When ODT is started (as explained in Section a i\ 

readiness to accept commanded k,, .ection 8.1) it indicates 

“TSl! 

L ha 2I^ t £ s^“^ e =2 3 rse P L°SS r'- a j» £££ Tr 

to certain words Thp a^enicei ^ or certain words or references 

8.3.1 Printout Formats 

rwt\sys-s xs-xl'x ss.s 
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8-1). OPT loo* *s fer the £•£-£? X? 

sr-ss. siss to h t e „ r; 

However, if no relocation 1 ^e relocation registers are 

is printed in absolute for . s number) the addresses are initially 
initialized to -1 (the g relocation register subsequently has 
its^contents^changed^it m ay then, depending on the conmand, qualify 
for relative form. 

to v ,„nie qUDDOS e relocation registers 1 and 2 contain 1000 and 
For example, PP <-><-her relocation registers contain numbers 

1004 respectively, and all other ^location Qccur slash 

mUCh ^d 9 causes ?he contents o? g the location to be printed; the line 
feS command (<LF» accesses the next sequential location) : 


*774/ 666000 <LF> 

0007 76 ,'606666 <LF> 
1706 0 6 6 6 ,'6066 60 <LF> 
i . 00 66 6 2 ,'66 0668 <LF> 

2 j 6 0 0 8 6 6 ,'660666 


(absolute location 1000) 
(absolute location 1002) 
(absolute location 1004) 


The printout format is controlled by the format register, $F. Normally 
S!s P SegJste? contains 0, in which case ODT prints addresses 
relatively whenever possible. $F may be opened and changed to a 
non-zero value, however, in which case all addresses will b ® pnnte 
in absolute form (see paragraph 8.3.4, Accessing Internal Registers). 


8.3.2 Opening, Changing, and Closing Locations 

An open location is one whose contents ODT prints for 
making those contents available for change. In a closed location, th 
contents are no longer available for change. Several commands 
used for opening and closing locations* 

Any command used to open a location when another location is 
open causes the currently open location to be closed. The contents o 
an open location may be changed by typing the new contents followed by 
a single-character command which requires no argument (i.e., ? , , 

RETURN, @, >, <) . 


The Slash, / 

One way to open a location is to type its address followed by a slash: 

*1.606/ 012746 

Location 1000 is open for examination and is available for change. 

If the contents of an open location are not to be changed, type f* 1 ® 
RETURN key and the location is closed; ODT prints an asterisk and 
waits for another command. However, to change the word, simply type 
the new contents before giving a command to close the location: 

*1666/ 012746 612345 <CR> 

* 
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In the example above, location 1000 now contains 012345 and is closed 
since the RETURN key was typed after entering the new contents, as 
indicated by ODT's second asterisk. 

Used alone, the slash reopens the last location opened: 

*1668/ 012345 2340 <CR> 

In the example above, the open location was closed by typing the 
RETURN key. ODT changed the contents of location 1000 to 002340 and 
then closed the location before printing the * *. The single slash 
command directed ODT to reopen the last location opened. This allowed 
verification that the word 002340 was correctly stored in location 
1000. 

Note again, that opening a location while another is open 
automatically closes the currently open location before opening the 
new location. 

Also note that if an odd numbered address is specified with a slash, 
ODT opens the location as a byte, and subsequently behaves as if a 
backslash had been typed (see the following paragraph). 


The Backslash, \ 

In addition to operating on words, ODT operates on bytes. One way to 
open a byte is to type the address of the byte followed by a 
backslash. (On the LT33 or LT35 terminal \ is typed by pressing the 
SHIFT key while typing the L key.) This causes not only the printing 
of the byte value at the specified address but also the interpreting 
of the value as ASCII code, and the printing of the corresponding 
character (if possible) on the terminal: 

*1001\ 161 =Ft 

A backslash typed alone reopens the last open byte. If a word was 
previously open, the backslash reopens its even byte: 

*1002/000004 \004 = 


The LINE FEED Key,<LF> 

If the LINE FEED key is typed when a location is open, ODT closes the 
open location and opens the next sequential location: 

*1006/ 002346 <LF> ( <LF> denotes typing the LINE FEED key) 
601062 /012740 

In this example, the LINE FEED key caused ODT to print the address of 
the next location along with its contents, and to wait for further 
instructions. After the above operation, location 1000 is closed and 
1002 is open. The open location may be modified by typing the new 
contents• 

If a byte location was open, typing the LINE FEED key opens the next 
byte location. 
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The Up-Arrow, t or A 

If the up-arrow (or circumflex) is typed when a location is open 
(up-arrow is produced on an LT33 or LT35 by typing SHIFT N) , ODT closes 
the open location and opens the previous location. To continue from 
the example above: 

*061002/ 612740 f 
001000 Z602340 

Now location 1002 is closed and 1000 is open. The open location may 
be modified by typing the new contents. 

If the opened location was a byte, then up-arrow opens the previous 
byte. 


The Back-Arrow, «- or _ 


If the back-arrow (or underline) is typed (via SHIFT 0 on an LT33 or 
LT35 terminal) to an open word, ODT interprets the contents of the 
currently open word as an address indexed by the Program Counter (PC) 
and opens the addressed location: 

*1006/ 000006 4- 
001016 /0 0 0 4 0 5 

Notice in this example that the open location, 1006, was indexed by 
the PC as if it were the operand of an instruction with address mode 
67 as explained in Chapter 5, 

A modification to the opened location can be made before a line feed, 
up-arrow, or back-arrow is typed. Also, the new contents of the 
location will be used for address calculations using the back-arrow 
command. Example: 

*180/ 6Q0222 4 <LF> (modify to 4 and open next location) 
000102 /0 0 6111 6f (modify to 6 and open previous location) 

600100 /000004 1004- (change to 100 and open location indexed 

000202 /12345 6 by PC) 


Open the Addressed Location, @ 

The at symbol @ (SHIFT P on the LT33 or LT35 terminal) may be used to 
optionally modify a location, close it, and then use its contents as 
the address of the location to open next. 

*100 6/ 001944 _ g (open location 1044 next) 

001044 /0 0 0 5 0 0 

*1066/ 001044 21060 (modify to 2100 and open location 

002100 /606167 2100) 
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Relative Branch Offset, > 

The right-angle bracket, >, will optionally modify a location, close 
it, and then use its low-order byte as a relative branch offset to the 
next word to be opened. For example: 


*1032/ 600467 361> (modify to 301 and interpret as a 
000636 /800010 relative branch) 

Note that 301 is a negative offset (-77). The offset is doubled before 
•it is added to the PC; therefore, 1034+(-176)=636. 


Return to Previous Sequence, < 


The left-angle bracket, <, allows the user to optionally modify a 
location, close it, and then open the next location of the previous 
sequence which was interrupted by a back-arrow, @, or right-angle 
bracket command. Note that back-arrow, @, or right-angle bracket 
causes a sequence change to the word opened. If a sequence change has 
not occurred, the left-angle bracket simply opens the next location as 
a LINE FEED does. This command operates on both words and bytes. 


*1032/ 000407 301> 

■ ~ < 

<? 

\005 = 


000626 

/ 0 0 0 010 

001034 

/ 0 010 4 0 

001040 

/ 0 0 0 4 0 5 

001035 

S 0 0 2 = < 

001036 

S004 = 


(> causes a sequence change) 
(return to original sequence) 
(@ causes a sequence change) 
(< now operates on byte) 

(< acts like <LF>) 


8.3.3 Accessing General Registers 0-7 

The program's general registers 0-7 are opened with a command in the 
following format: 

*$n/ 

where n is the integer representing the desired register (in the range 
0 through 7). When opened, these registers can be examined or changed 
by typing in new data as with any addressable location. For example: 

*$0/ 000033 <CR> (R0 was examined and closed) 

i 

*$4/ 000474 464<CR> (R4 was opened, changed, and closed) 

* 

The example above can be verified by typing a slash in response to 
ODT's asterisk: 

*/ 000464 


The LINE FEED, up-arrow, back-arrow or @ command may be used when a 
register is open. 


8-9 





















On-Line Debugging Technique 


8,3.4 Accessing Internal Registers 

The program's Status Register contains the condition codes of the most 
recent operational results and the interrupt priority level of the 
object program. It is opened by typing $S. For example: 


*$5/ 000311 

$S represents the address of the Status Register. In response to $S 
in the example above, ODT printed the 16-bit word, of which only the 
low-order eight bits are meaningful. Bits 0-3 indicate whether a 
carry, overflow, zero, or negative (in that order) has resulted, and 
bits 5-7 indicate the interrupt priority level (in the range 0-7) of 
the object program. (Refer to the PDP-11 Processor Handbook for the 
Status Register format.) 


The $ is used to open certain other internal locations listed in Table 
8 - 2 : 


Table 8-2 

Internal Registers 


Register 

Function 

$B 

location of the first word of the breakpoint table 
(see Section 8.3.6). 

$M 

mask location for specifying which bits are to be 
examined during a bit pattern search (see Section 
8.3.9). 

$P 

location defining the operating priority of ODT 
(see Section 8.3.15). 

$s 

location containing the condition codes (bits 0-3) 
and interrupt priority level (bits 5-7) (explained 
above). 

$c 

location of the Constant Register (see Section 
8.3.10). 

$R 

location of Relocation Register 0, the base of the 
Relocation Register table (see Section 8.3.13). 

$F 

location of Format Register (see Section 8.3.1). 


8.3.5 Radix 50 Mode, X 

The Radix 50 mode of packing certain ASCII characters three to a word 
is employed by many DEC-supplied PDP-11 system programs, and may be 
employed by any programmer via the MACRO Assembler's ".RAD50" 
directive. ODT provides a method for examining and changing memory 
words packed in this way with the X command. 

When a word is opened and the X command is typed, ODT converts the 
contents of the opened word to its 3-character Radix 50 equivalent and 
prints these characters on the terminal. One of the responses in 
Table 8-3 can then be typed: 
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Table 8-3 


Radix 50 Terminators 


Response 

Effect 

RETURN key <CR> 

Closes the currently open location. 

LINE FEED key <LF> 

Closes the currently open location and 
opens the next one in sequence. 

t key 

Closes the currently open location and 
opens the previous one in sequence. 

Any three 
characters whose 
octal code is 040 
(space) or greater. 

Converts the three specified characters 
into packed Radix 50 format. 

Legal Radix 50 characters for this last response are: 

. $ Space 

0 through 9 A through Z 


If any other characters are typed, the resulting binary number is 
unspecified (that is, no error message is printed and the result is 
unpredictable)• Exactly three characters must be typed before ODT 
resumes its normal mode of operation. After the third character is 
typed, the resulting binary number is available to be stored in the 
opened location by closing the location in any one of the ways listed 
in Table 8-3. Example: 

*1089/ 042431 X = KB I CBft <CR> 

*‘1000/011421 X = C- B ft 


NOTE 

After ODT has converted the three 
characters to binary, the binary number 
can be interpreted in one of many 
different ways, depending on the command 
which follows. For example: 

*1234/ 063337 X = PRQ XIT/ 613704 

Since the Radix 50 equivalent of XIT is 
113574, the final slash in the example 
will cause ODT to open location 113574 
if it is a legal address. (Refer to 
paragraph 8.5 for a discussion of 
command legality and detection of 
errors.) 


8.3.6 Breakpoints 

The breakpoint feature facilitates monitoring the progress of program 
execution. A breakpoint may be set at any instruction which is not 
referenced by the program for data. When a breakpoint is set, ODT 
replaces the contents of the breakpoint location with a trap 
instruction so that program execution is suspended when a breakpoint 
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is encountered. The original contents of the breakpoint location are 
restored, and ODT regains control. 

With ODT, up to eight breakpoints, numbered 0 through 7, can be set at 
any one time. A breakpoint is set by typing the address of the 
desired location of the breakpoint followed by ;B. Thus r;B sets the 
next available breakpoint at location r. (If all 8 breakpoints have 
been set, ODT ignores the r;B command.) Specific breakpoints may be 
set or changed by the r;nB command where n is the number of the 
breakpoint. For example: 

(sets breakpoint 0) 

(sets breakpoint 1) 

(sets breakpoint 2) 

(resets breakpoint 1) 


The ;B command removes all breakpoints. Use the ;nB command to remove 
only one of the breakpoints, where n is the number of the breakpoint. 
For example: 

*; 26 (removes the second breakpoint) 

i 

A table of breakpoints is kept by ODT and may be accessed by the user. 
The $B/ command opens the location containing the address of 
breakpoint 0. The next seven locations contain the addresses of the 
other breakpoints in order, and can be sequentially opened using the 
LINE FEED key. For example: 

*$6/001020 <LF> 
nnnnnn /0 0.10 32 <LF> 

nnnnnn /nnnnnn (nnnnnn=address internal to ODT) 

In this example, breakpoint 2 is not set. The contents printed is an 
address internal to ODT and can be determined by checking the Linker 
Load Map (see Chapter 6). 

It should be noted that a repeat count in a Proceed command refers 
only to the breakpoint that has most recently occurred. Execution of 
other breakpoints encountered is determined by their own repeat 
counts. 


* 1020;6 
*1030;B 
*1040;B 
*1032;IB 
* 


8.3.7 Running the Program, r;G and r;P 

Program execution is under control of ODT. There are two commands for 
running the program: r;G and r;P. The r;G command is used to start 

execution (Go) and r;P to continue (Proceed) execution after halting 
at a breakpoint. For example: 

*1000; G 

Execution is started at location 1000. The program runs until a 
breakpoint is encountered or until program completion, unless it gets 
caught in an infinite loop, in which case it must be either restarted 
or reentered as explained in Section 8.1. 

Upon execution of either the r;G or r;P command, the general registers 
0-6 are set to the values in the locations specified as $0-$6 and the 
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processor Status Register is set to the value in the location 
specified as $S. 

When a breakpoint is encountered, execution stops and ODT prints Bn; 
(where n is the breakpoint number), followed by the address of the 
breakpoint. Locations can then be examined for expected data. For 
example: 


*1010; 2B 
*1000;G 

b:<; 001010 

* 


(breakpoint 3 is set at location 1010) 
(execution started at location 1000) 
(execution stopped at location 1010) 


To continue program execution from the breakpoint, type ;P in response 
to ODT 1 s last *. 


When a breakpoint is set in a loop, it may be desirable to allow the 
program to execute a certain number of times through the loop before 
recognizing the breakpoint. This can be done by setting a proceed 
count using the k;P command; this command specifies the number of 
times the breakpoint is to be encountered before program execution is 
suspended (on the kth encounter). The count, k, refers only to the 
numbered breakpoint which most recently occurred. A different proceed 
count may be specified for the breakpoint when it is encountered. 
Thus: 


B3;001019 

*1026; 2B 
*4; P 

B2i 001026 

* 


(execution halted at breakpoint 3) 
(reset breakpoint 3 at location 1026) 
(set proceed count to 4 and 
continue execution; loop through 
breakpoint three times and halt on 
fourth occurrence of the breakpoint) 


Following the table of breakpoints (as explained in Section 8.3.6) is 
a table of proceed command repeat counts for each breakpoint. These 
repeat counts can be inspected by typing $B/ and nine LINE FEEDS. The 
repeat count for breakpoint 0 is printed (the first seven LINE FEEDS 
cause the table of breakpoints to be printed; the eighth types the 
single instruction mode, explained in the next section, and the ninth 
LINE FEED begins the table of proceed command repeat counts). The 
repeat counts for breakpoints 1 through 7, and the repeat count for 
the single-instruction trap follow in sequence. Before a proceed 
count is assigned a value by the user, it is set to 0; after the count 
has been executed, it is set to -1. Opening any one of these provides 
an alternative way of changing the count as the location, once open, 
can have its contents modified in the usual manner by typing the new 
contents and then the RETURN key. For example: 


nnnnnn 

,'001026 

<LF> 

nnnnnn 

,'006628 

<LF> 

nnnnnn 

Z000000 

15 <LF> 

nnnnnn 

,'000080 

<LF> 


nnnnnn 

,'000000 <LF> 

nnnnnn 

/nnnnnn 


(address of breakpoint 7) 

(single instruction address) 

(count for breakpoint 0; change to 15) 
(count for breakpoint 1) 


(count for breakpoint 7) 

(repeat count for single instruction 
mode; the single instrucion address 
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is an address internal to the user 
program if single instrucion mode is 
used) 

The address indicated as the single instruction address and the repeat 
count for single instruction mode are explained next. 


8.3.8 Single Instruction Mode 

With this mode the number of instructions to be executed before 
suspension of the program run can be specified. The Proceed command, 
instead of specifying a repeat count for a breakpoint encounter, 
specifies the number of succeeding instructions to be executed. Note 
that breakpoints are disabled when single instruction mode is 
operative. 

Commands for single instruction mode are: 

;nS Enables single instruction mode (n can have any 

non-zero value and serves only to distinguish this 
form from the form ;S)• Breakpoints are disabled. 

n?P Proceeds with program run for next n instructions 

before reentering ODT (if n is missing, it is 
assumed to be 1). Trap instructions and associated 
handlers can affect the Proceed repeat count. See 
Section 8.4.2. 

;S Disables single instruction mode. 

When the repeat count for single instruction mode is exhausted and the 
program suspends execution, ODT prints: 

B8;nnnnnn 

where nnnnnn is the address of the next instruction to be executed. 
The $B breakpoint table contains this address following that of 
breakpoint 7. However, unlike the table entries for breakpoints 0-7, 
direct modification has no effect. 

Similarly, following the repeat count for breakpoint 7 is the repeat 
count for single instruction mode. This table entry may be directly 
modified and thus is an alternative way of setting the 
single-instruction mode repeat count. In such a case, ;P implies the 
argument set in the $B repeat count table rather than an assumed 1. 


8.3.9 Searches 

With ODT all or any specified portion of memory can be searched for 
any specific bit pattern or for references to a particular location. 
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Word Search, r;W 

3 ?° rd search ' the mask and search limits must be 
specitied. The location represented by $M is used to specify the mask 
search. $M/ opens the mask register. The next two sequential 
locations (opened by LINE FEEDs) contain the lower and upper limits of 
BitS ? Gt t0 1 in the mask are examined during the Search; 
™™L bltS arS 1 ^? ored * Then the search object and the initiating 
command are given using the r;W command where r is the search object 

S e set a t o m ? £h fOUn ^' 6aCh bit Set t0 1 in the search °bject 

is set to 1 in the word being searched over the mask range) toe 

matching word is printed. For examples 


**M/ 900088 177400 <LF> 
nnnnnn ,'090000 leea <LF> 
nnnnnn ,-'000000 1040 <CR> 
*400;W 

901010 Z090770 

001034/000404 


(test high-order eight bits) 
(set low address limit) 

(set high address limit) 
(initiate word search) 


In the above example, nnnnnn is an address internal to ODT• this 
location varies and is meaningful only for reference purposes.* In the 
a® the slash was used to open $M which now contains 

177400; the LINE FEEDs opened the next two sequential locations which 
now contain the upper and lower limits of the search. 

In the search process an exclusive OR (XOR) is performed with toe word 
^L en , tlY , being . exa rained and the search object, and the result is 
ANDed to the mask, if this result is zero, a match has been found and 

..K 0n the terminal. Note that if toe mask is zero, all 
locations within the limits are printed. 

Typing CTRL U during a search printout terminates the search. 


Effective Address Search, r;E 


ODT provides a search for words which address a specified location. 
Open the mask register only to gain access to the low and high limit 
registers. After specifying the search limits (as explained for the 

Ch iu type comm and r;E (where r is the effective address) 
to initiate the search. 


Words which are either an absolute address 
rslativs address offset, or a relative 
address, are printed after their addresses. 


(argument r itself), a 
branch to the effective 
For example: 


»$M /17?400 <LF> 
nnnnnn /901900 1018 
nnnnnn /801049 I960 
*1034;E 

081016 /901006 

081054 /002 767 

*1020;E 

091022 /177774 

001930 /991020 


(open mask register only to gain 
<LF> access to search limits) 

<CR> 

(initiating search) 

(relative branch) 

(relative branch) 

(initiating a new search) 
(relative address offset) 
(absolute address) 
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Particular attention should be given to the reported effective address 
references because a word may have the specified bit pattern of an 
effective address without actually being so used. ODT reports all 
possible references whether they are actually used as such or not. 

Typing CTRL U during a search printout terminates the search. 


8.3.10 The Constant Register, r;C 

It is often desirable to convert a relocatable address into its value 
after relocation or to convert a number into its two's complement, and 
then to store the converted value into one or more places in a 
program. The Constant Register provides a means of accomplishing tnis 
and other useful functions. 

When r;C is typed, the relocatable expression r is evaluated to its 
6 -digit octal value and is both printed on the terminal and stored in 
the Constant Register. The contents of the Constant Register may be 
invoked in subsequent relocatable expressions by typing the letter C. 
Examples follow: 

*-4432; Cfi71346 (the two's complement of 4432 is placed 

in the Constant Register) 


*6622/062701__C <CR> (the contents of the Constant Register 

are stored in location 6632) 

*1000;1R (relocation Register 1 is set to 1000) 

*i. 4272; C=0052?2 (relative location 4272 is reprinted as 
~ an absolute location and stored in the 

Constant Register) 


8.3.11 Memory Block Initialization, ;F and ;I 

The Constant Register can be used in conjunction with the commands ;F 
and ;I to set a block of memory to a given value. While the most 
common value required is zero, other possibilities are plus one, minus 
one, ASCII space, etc. 

When the command ;F is typed, ODT stores the contents of the Constant 
Register in successive memory words starting at the memory word 
address specified in the lower search limit, and ending with the 
address specified in the upper search limit. 

When the command ;I is typed, the low-order 8 bits in the Constant 
Register are stored in successive bytes of memory starting at the byte 
address specified in the lower search limit and ending with the byte 
address specified in the upper search limit. 

For example, assume relocation register 1 contains 7000, 2 contains 
10000, and 3 contains 15000. The following sequence sets word 
locations 7000-7776 to zero, and byte locations 10000-14777 to ASCII 
spaces. 
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*<(1/ 008080 <LF> 
nnnnnn ,'000000 1, Q LF> 
nnnnnn ,'008000 2, -2 <LF> 

*0;c =006000 

*; F 


(open mask register to gain access 
to search limits) 

(set lower limit to 7000) 

(set upper limit to 7776) 

(Constant Register set to zero) 
(Locations 7000—7776 set to zero) 


*<(1/000000 <LF> 
nnnnnn/ 00 7 00 6 2, 0 <LF> 
nnnnnn,/0Q7 7 76 3, -1 <CR> 
*40;C — 8 0 0 0 4 0 
*; I 
* 


(set lower limit to 10000) 

(set upper limit to 14777) 

(Constant Register set to 40 
(SPACE)) 

(Byte locations 10000-14777 are set 
to value in low-order 8 bits of 
Constant Register) 


8.3.12 Calculating Offsets, r;0 

Relative addressing and branching involve the use of an offset—the 
number of words or bytes forward or backward from the current location 
to the effective address. During the debugging session it may be 
necessary to change a relative address or branch reference by 
replacing one instruction offset with another. ODT calculates the 
offsets in response to the r;0 command. 


The command r;0 causes ODT to print the 16-bit and 8-bit offsets from 
the currently open location to address r. For example: 

*346/ 000034 4 14; 0 008044 022 22 <CR> 

0 9 0 9 2 2 

In the example, location 346 is opened and the offsets from that 
location to location 414 are calculated and printed. The contents of 
location 346 are then changed to 22 (the 8-bit offset) and verified on 
the next line. 

The 8-bit offset is printed only if it is in the range -128(decimal) 
to 127(decimal) and the 16-bit offset is even, as was the case above. 
Fore xample, the offset of a relative branch is calculated and 
modified as follows: 

*1034/ 103421 1034;0 177776 377 \821 = 377 <CR> 

*/103777 

Note that the modified low-order byte 377 must be combined with the 
unmodified high-order byte. 


8.3.13 Relocation Register Commands, r;nR, ;nR, ;R 

The use of the relocation registers is defined in Section 8.2. At the 
beginning of a debugging session it is desirable to preset the 
registers to the relocation biases of those relocatable modules which 
will be receiving the most attention. 

This can be done by typing the relocation bias, followed by a 
semicolon and the specification of relocation registers, as follows: 
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r;nR 

r may be any relocatable expression and n is an integer from 0 to 7. 

If n is omitted it is assumed to be 0. As an example: 

*1800;5R (puts 1000 into relocation register 5) 

*5, 100; 5R (effectively adds 100 to the contents 

* of relocation register 5) 

Once a relocation register is defined, it can be used to reference 
relocatable values. For example: 

*280051R (puts 2000 into relocation register 1) 

*1,2176/ 892465 (examines contents of location 4176) 

*i,3712;0B (sets a breakpoint at location 5712) 

In certain uses, programs may be relocated to an address below that at 
which they were assembled. This could occur with PIC code (Position 
Independent Code) which is moved without the use of the Linker. In 
this case the appropriate relocation bias would be the two s 
complement of the actual downward displacement. One method for easily 
evaluating the bias and putting it in the relocation register is 

illustrated in the following example. 

Assume a program was assembled at location 5000 and was moved to 
location 1000. Then the sequence: 

*1000;1R 
*1,—5000;1R 
* 

enters the two's complement of 4000 in relocation register 1, as 
desired. 

Relocation registers are initialized to -1, so that unwanted 

relocation registers never enter into the selection process when ODT 

searches for the most appropriate register. 

To set a relocation register to -1, type ;nR. To set all relocation 
registers to -1, type ;R. 

ODT maintains a table of relocation registers, beginning at the 
address specified by $R. Opening $R ($R/) opens relocation register 0. 
Successively typing a line feed opens the other relocation registers 
in sequence. When a relocation register is opened in this way, it may 
be modified like any other memory location. 


8.3.14 The Relocation Calculators,'nR and n! 

When a location has been opened, it is often desirable to relate the 
relocated address and the contents of the location back to their 
relocatable values. To calculate the relocatable address of the 
opened location relative to a particular relocation bias, type n!, 
where n specifies the relocation register. This calculator works with 
opened bytes and words. If n is omitted, the relocation register 
whose contents are closest but less than or equal to the opened 
location is selected automatically by ODT. In the following example, 
assume that these conditions are fulfilled by relocation register 2, 


January 1976 


8-18 







On-Line Debugging Technique 

which contains 2000. To find the most likely module that a given 
opened byte is in: 

♦258BS 011 = ! =2;060500 

Typing nR after opening a word causes ODT to print the octal number 
which equals the value of the contents of the opened location minus 
the contents of relocation register n. If n is omitted, ODT selects 
the relocation register whose contents are closest but less than or 
equal to the contents of the opened location. For example, assume the 
relocation bias stored in relocation register 1 is 7000; then: 

*1,500/ 0600Q0 1R = 1* 171000 

The value 171000 is the content of 1,500, relative to the base 7000. 
An example of the use of both relocation calculators follows. 

If relocation register 1 contains 1000, and relocation register 2 
contains 2000, then to calculate the relocatable addresses of location 
3000 and its contents, relative to 1000 and 2000, the following can be 
performed. 

♦ 3800/0D0410 1 1 =1; 662600 2 ? =2; 061000 1R = 1, 177416 2R = 2, 176410 


8.3.15 ODT Priority Level, $P 

$P represents a location in ODT that contains the interrupt (or 
processor) priority level at which ODT operates. If $P contains the 
value 377, ODT operates at the priority level of the processor at the 
time ODT is entered. Otherwise $P may contain a value between 0 and 7 
corresponding to the fixed priority at which ODT operates. 

To set ODT to the desired priority level, open $P. ODT prints the 
present contents, which may then be changed: 

♦$P/ 000006 377 <CR> 

♦ 

If $P is not specified, its value is seven. 

ODT priority must be set to 0 if ODT is being used in an F/B 
environment with another job running. 

Breakpoints may be set in routines which run at different priority 
levels. For example, a program running at a low priority may use a 
device service routine which operates at a higher priority level. If 
a breakpoint occurs from a low-priority routine, ODT operates at a low 
priority? if an interrupt occurs from a high priority routine, the 
breakpoints in the high priority routine will not be recognized since 
they were removed when the low priority breakpoint occurred. That is, 
interrupts set at a priority higher than the one at which ODT is 
running will occur and any breakpoints will not be recognized. ODT 
disables all breakpoints from the program whenever it gains control. 
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Breakpoints are enabled when ;P and ;G commands are executed. For 
example: 


♦ $ P / 8 6 6 0 Q ? 5 

*1000;B 

*2000;B 

*1000;G 

B8;001600 

* (an interrupt occurs and is serviced) 

If a higher level interrupt occurs while ODT is waiting for input the 
interrupt will be serviced, and no breakpoints will be recognized. 

8.3.16 ASCII Input and Output, r;nA 

ASCII text may be inspected and changed by the command: 

r ;nA 

where r is a relocatable expression, and n is a character count. If n 
is omitted it is assumed to be 1. ODT prints n characters starting at 
location r, followed by a carriage return/line feed. Type one of the 
following: 

<CR> ODT outputs a carriage return/line feed and 

an asterisk and waits for another command. 

<LF> ODT opens the byte following the last byte 

output. 

Up to n characters of text 

ODT inserts the text into memory, starting at 
location r. If fewer than n characters are 
typed, terminate the command by typing 
CTRL U, causing a carriage return/line 
feed/asterisk to be output. However, if 
exactly n characters are typed, ODT responds 
with a carriage return/line feed, the address 
of the next available byte and a carriage 
return/line feed/asterisk. 

ODT does not check the magnitude of n. 

8.4 PROGRAMMING CONSIDERATIONS 

Information in this section is not necessary for the efficient use of 
ODT. However, it does provide a better understanding of how ODT 
performs some of its functions and in certain difficult debugging 
situations, this understanding is necessary. 

8.4.1 Functional Organization 

The internal organization of ODT is almost totally modularized into 
independent subroutines. The internal structure consists of three 
major functions: command decoding, command execution, and various 
utility routines. 

The command decoder interprets the individual commands, checks for 
command errors, saves input parameters for use in command execution, 
and sends control to the appropriate command execution routine. 
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The command execution routines take parameters saved by the command 
decoder and use the utility routines to execute the specified command. 
Command execution routines exit either to the object program or back 
to the command decoder. 

The utility routines are common routines such as SAVE-RESTORE and I/O. 
They are used by both the command decoder and the command executers. 

8.4.2 Breakpoints 

The function of a breakpoint is to give control to ODT whenever the 
user program tries to execute the instruction at the selected address. 
Upon encountering a breakpoint, all of the ODT commands can be used to 
examine and modify the program. 

When a breakpoint is executed, ODT removes all the breakpoint 
instructions from the user's code so that the locations may be 
examined and/or altered. ODT then types a message on the terminal of 
the form Bn;k where k is the breakpoint address (and n is the 
breakpoint number)• The breakpoints are automatically restored when 
execution is resumed, 

A major restriction in the use of breakpoints is that the word where a 
breakpoint was set must not be referenced by the program in any way 
since ODT altered the word. Also, no breakpoint should be set at the 
location of any instruction that clears the T-bit. For examples 

MOV #240,177776 ;SET PRIORITY TO LEVEL 5 

NOTE 

Instructions that cause or return from 
traps (e.g., EMT, RTI) are likely to 
clear the T-bit, since a new word from 
the trap vector or the stack is loaded 
into the Status Register. 

A breakpoint occurs when a trace trap instruction (placed in the user 
program by ODT) is executed. When a breakpoint occurs, the following 
steps are taken: 

1. Set processor priority to seven (automatically set by trap 
instruction). 

2. Save registers and set up stack. 

3. If internal T-bit trap flag is set, go to step 13. 

4. Remove breakpoints. 

5. Reset processor priority to ODT's priority or user's 
priority. 

6. Make sure a breakpoint or single-instruction mode caused the 
interrupt. 

7. If the breakpoint did not cause the interrupt, go to step 15. 

8. Decrement repeat count. 

9. Go to step 18 if non-zero; otherwise reset count to one. 

10. Save terminal status. 

11. Type message about the breakpoint or single-instruction mode 
interrupt. 
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12. Go to command decoder. 

13. Clear T-bit in stack and internal T-bit flag. 

14. Jump to the Go processor. 

15. Save terminal status. 

16. Type BE (Bad Entry) followed by the address. 

17. Clear the T-bit, if set, in the user status and proceed to 
the command decoder. 

18. Go to the Proceed processor, bypassing the TT restore 
routine. 

Note that steps 1-5 inclusive take approximately 100 microseconds 
during which time interrupts are not permitted (ODT is running at 
level 7). 

When a proceed (;P) command is given, the following occurs: 

1. The proceed is checked for legality. 

2. The processor priority is set to seven. 

3. The T-bit flags (internal and user status) are set. 

4. The user registers, status, and Program Counter are restored. 

5. Control is returned to the user. 

6 . When the T-bit trap occurs, steps 1, 2, 3, 13, and 14 of the 
breakpoint sequence are executed, breakpoints are restored, 
and program execution resumes normally. 

When a breakpoint is placed on an IOT, EMT, TRAP, or any instruction 
causing a trap, the following occurs: 

1. When the breakpoint occurs as described above, ODT is 
entered. 

2. When ;P is typed, the T-bit is set and the IOT, EMT, TRAP, or 
other trapping instruction is executed. 

3. This causes the current PC and status (with the T-bit 
included) to be pushed on the stack. 

4. The new PC and status (no T-bit set) are obtained from the 
respective trap vector. 

5. The whole trap service routine is executed without any 
breakpoints. 

6 . When an RTI is executed, the saved PC and PS (including the 
T-bit) are restored. The instruction following the 
trap-causing instruction is executed. If this instruction is 
not another trap-causing instruction, the T-bit trap occurs, 
causing the breakpoints to be reinserted in the user program. 
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or the single-instruction mode repeat count to be 
decremented. If the following instruction is a trap-causing 
instruction, this sequence is repeated starting at step 3. 


NOTE 

Exit from the trap handler must be via 
the RTI instruction. Otherwise, the 
T-bit is lost. ODT can not regain 
control since the breakpoints have not 
been reinserted yet. 


Note that the ;P command is illegal if a breakpoint has not occurred 
(ODT responds with ?); ;P is legal, however, after any trace trap 
entry. 

The internal breakpoint status words have the following format: 

1. The first eight words contain the breakpoint addresses for 
breakpoints 0-7. (The ninth word contains the address of the 
next instruction to be executed in single-instruction mode.) 

• 2. The next eight words contain the respective repeat counts. 

The following word contains the repeat count for 
single-instruction mode.) 

These words may be changed at will, either by using the breakpoint 
commands or by direct manipulation with $B. 

When program runaway occurs (that is, when the program is no longer 
under ODT control, perhaps executing an unexpected part of the program 
where a breakpoint has not been placed), ODT may be given control by 
pressing the HALT key to stop the computer,and restarting ODT (see 
Section 8.1). ODT prints *, indicating that it is ready to accept a 
command. 

If the program being debugged uses the teleprinter for input or 
output, the program may interact with ODT to cause an error since ODT 
uses the teleprinter as well. This interactive error will not occur 
when the program being debugged is run without ODT. 

Note the following rules concerning the ODT break routine: 

1. If the teleprinter interrupt is enabled upon entry to the ODT 
break routine, and no output interrupt is pending when ODT is 
entered, ODT generates an unexpected interrupt when returning 
control to the program. 

2. If the interrupt of the teleprinter reader (the keyboard) is 
enabled upon entry to the ODT break routine, and the program 
is expecting to receive an interrupt to input a character, 
both the expected interrupt and the character are lost. 

3. If the teleprinter reader (keyboard) has just read a 
character into the reader data buffer when the ODT break 
routine is entered, the expected character in the reader data 
buffer is lost. 
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8.4.3 Searches 

The word search allows the user to search for bit patterns in 
specified sections of memory. Using the $M/ command, the user 
specifies a mask, a lower search limit ($M+2), and an upper search 
limit ($M+4). The search object is specified in the search command 
itself. 

The word search compares selected bits (where ones appear in the mask) 
in the word and search object. If all of the selected bits are equal, 
the unmasked word is printed. 

The search algorithm is: 

1. Fetch a word at the current address. 

2. XOR (exclusive OR) the word and search object. 

3. AND the result of step 2 with the mask. 

4. If the result of step 3 is zero, type the address of the 
unmasked word and its contents. Otherwise, proceed to step 

5. 

5. Add two to the current address. If the current address 'is 
greater than the upper limit, type * and return to the 
command decoder, otherwise go to step 1. 

Note that if the mask is zero, ODT prints every word between the 
limits, since a match occurs every time (i.e., the result of step 3 is 
always zero)• 

In the effective address search, ODT interprets every word in the 
search range as an instruction which is interrogated for a possible 
direct relationship to the search object. The mask register is opened 
only to gain access to the search limit registers. 

The algorithm for the effective address search is (where (X) denotes 
contents of X, and K denotes the search object): 

1. Fetch a word at the current address X. 

2. If (X)=K [direct reference], print contents and go to step 5. 

3. If (X)+X+2=K [indexed by PC], print contents and go to step 

5. 

4. If (X) is a relative branch to K, print contents. 

5. Add two to the current address. If the current address is 
greater than the upper limit, perform a carriage return/line 
feed and return to the command decoder; otherwise, go to 
step 1. 


8.4.4 Terminal Interrupt 

Upon entering the TT SAVE routine, the following occurs: 
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1. Save the LSR status register (TKS)• 

2. Clear interrupt enable and maintenance bits in the TKS. 

3. Save the TT status register (TPS). 

4. Clear interrupt enable and maintenance bits in the TPS. 
To restore the TT: 

1. Wait for completion of any I/O from ODT. 

2. Restore the TKS. 

3. Restore the TPS. 


NOTES 

If the TT printer interrupt is enabled 
upon entry to the ODT break routine, the 
following may occur: 

1. If no output interrupt is 

pending when ODT is entered, an 
additional interrupt always 
occurs when ODT returns control 
to the user. 

2. If an output interrupt is 

pending upon entry, the 

expected interrupt occurs when 

the user regains control. 

If the TT reader (keyboard) is busy or 
done, the expected character in the 
reader data buffer is lost. 

If the TT reader (keyboard) interrupt is 
enabled upon entry to the ODT break 
routine, and a character is pending, the 
interrupt (as well as the character) is 
lost. 


8.5 ODT ERROR DETECTION 

ODT detects two types of error: illegal or unrecognizable command and 
bad breakpoint entry. ODT does not check for the legality of an 
address when commanded to open a location for examination or 
modification. Thus the command: 

♦177774/ 

7M-TRRF TO 4 883362 

references nonexistent memory, thereby causing a trap through the 
vector at location 4. If this vector has not been properly 
initialized, unpredictable results occur. 
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Typing something other than a legal command causes ODT to ignore the 
command, prints 

(echoes illegal command)? 

* 

and wait for another command. Therefore, to cause ODT to ignore a 
command just typed, type any illegal character (such as 9 or RUBOUT) 
and the command will be treated as an error, i.e., ignored. 

ODT suspends program execution whenever it encounters a breakpoint, 
i.e., traps to its breakpoint routine. If the breakpoint routine is 
entered and no known breakpoint caused the entry, ODT prints: 

BEnnnnnn 

* 

and waits for another command. BEnnnnnn denotes Bad Entry from 
location nnnnnn. A bad entry may be caused by an illegal trace trap 
instruction, setting the T-bit in the status register, or by a jump to 
the middle of ODT. 
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PROGRAMMED REQUESTS 


A number of services at the machine language level which the monitor 
regularly provides to system programs are also available to 

user-written programs. These include services for file manipulation, 
command interpretation, and facilities for input and output 

operations. User programs call these monitor services by means of 
programmed requests", which are assembler macro calls written into 
the user program and interpreted by the monitor at program execution 
time. 


NOTE 

Programmed requests used in Version 2 
differ from those used in Version 1; for 
example, the channel number in Version 1 
was limited to the range 0-17, where it 
is not in Version 2; blank fields in 
macro calls were not allowed in Version 
1, and are in Version 2; a .area 
argument points to an argument list in 
Version 2, where arguments were pushed 
on the stack in Version 1. 

Programs written for use under Version 1 
will assemble and execute properly when 
the ..VI.. macro call (explained in 
Section 9.3.1.5) is included, but it is 
to the user's advantage to convert these 
programs so they use the new Version 2 
macro calls wherever possible. Only 
macro calls which are used with the 
current version of RT-11 (Version 2) are 
discussed in this chapter. See Section 
9.5 for instructions on converting 
Version 1 macro calls to the Version 2 
format. 



The FORTRAN programmer should note that the system subroutine library 
(SYSLIB) gives him the same capability (under FORTRAN) to use the 
programmed requests which are available to the machine language 
programmer and described in this chapter. SYSLIB users should first 
read this chapter and then read Appendix O. 
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9.1 FORMAT OF A PROGRAMMED REQUEST 

The basis of a programmed request is the EMT instruction , used to 
communicate information to the monitor. When an EMT is executed, 
control is passed to the monitor, which extracts appropriate 
information from the EMT and executes the function required. The 
low-order byte of the EMT instruction contains a code which is 
interpreted as: 


Low-Order Byte 

of EMT Meaning 

377 Reserved; RT-11 ignores this EMT and returns 

control to the user program immediately. 

376 Used internally by the RT-11 monitor; this EMT 

code should never be used by user programs. 

375 Programmed request with several arguments: RO 

must point to a list of arguments which designates 
the specific function. 

374 programmed request with one argument: RO contains 

a function code in the high-order byte and a 
channel number (see Section 9.2.1) or 0 in the 
low-order byte. 

360-373 Used internally by the RT-11 monitor; these EMT 

codes should never be used by user programs. 

340-357 Programmed request with arguments on the stack 

and/or in RO. 

0-337 Version 1 programmed request. These EMTs use 

arguments both on the stack and in RO• They are 
supported for binary compatability with Version 1 
programs. 

A programmed request consists of a macro call followed, where 
necessary, by one or more arguments. Arguments supplied to a macro 
call must be legal assembler expressions since arguments will be used 
as source fields in MOV instructions when the macros are expanded at 
assembly time. The following two formats are used: 


1. PRGREQ ARG1,ARG2,...ARGN 

2. PRGREQ AREA,ARG1,ARG2,.•.ARGN 

Form 1 above contains the arguments ARG1 through ARGN; no argument 
list pointer is required. Macros of this form generate either an EMT 

374 or one of the EMTs 340-357. Certain arguments for this form may be 
omitted; refer to the listing of SYSMAC.SML in Appendix D. 

In form 2 above, AREA is a pointer to the argument list which contains 
the arguments ARGl through ARGN. This form always causes an EMT 375 
to be generated. Blank fields are permitted; however, if the AREA 
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argument is blank, the macro assumes that RO points to a valid 
argument block (see Section 9.2.3). If any of the fields ARG1 to ARGN 
are blank, the corresponding entries in the argument list are left 

untouched. Thus, 

.PRGREQ AREA,A1,A2 

points RO to the argument block at AREA and fills in the first and 
second arguments, while: 

.PRGREQ AREA 

points RO to the block, and fills in the first word but does not fill 

in any other arguments. 

The call: 


.PRGREQ ,A1 

assumes RO points to the argument block and fills in the A1 argument, 
but leaves the A2 argument alone. The call: 

.PRGREQ 

generates only an EMT 375 and assumes that both RO and the block to 
which it points are properly set up. 

The arguments to RT-11 programmed request macros all serve as the 
source field of a MOV instruction which moves a value into the 
argument block or RO. For example: 

.PRGREQ CHAR 

expands into: 

MOV CHAR,RO 
EMT 357 

Care should be taken to make certain that the arguments specified are 
legal source fields and that the address accurately represents the 
value desired. If the value is a constant, immediate mode [#] should 
be used; if the value is in a register, the register mnemonic [Rn] 
should be used; if the value is indirectly addressed, the appropriate 
register convention is necessary [@Rn], and if the value is in memory, 
the label of the location whose value is the argument is used. 

Following are some examples of both correct and incorrect macro calls. 
Consider the general request: 

.PRGREQ .AREA,.ARG1,...ARGN 
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A more common way of writing a request of this form is: 

.PRGREQ #AREA,#ARG1,...#ARGN 

In this format, the address of AREA is put directly into the argument 
list. AREA is the tag which indicates the beginning of the argument 
block. For example: 

.PRGREQ #AREA,#4 


AREA: .BLKW 3 

When a direct numerical argument is required, the # causes the correct 
value to be put into the argument block. For example: 

.PRGREQ #AREA,#4 

is correct, while: 

.PRGREQ #AREA,4 

is not. This form interprets the 4 as meaning "move the contents of 
location 4 into the argument block", where the number 4 itself should 
be moved into the block. 

If the request is written as: 

.PRGREQ AREA,#4 

it is interpreted as "use the contents of location AREA as the list 
pointer", when the address of AREA is actually desired. This 
expansion could be used with the following form: 

.PRGREQ LIST1,#4 


• 

LIST1: AREA 

AREA: .BLKW3 

In this case, the content of location LIST1 is the address of the 
argument list. Similarly, this form is correct: 

.PRGREQ LIST1,NUMBER 
LIST1: AREA 

NUMBER: 4 

In this case, the contents of the locations IIST1 and NUMBER are the 
argument list pointer and data value, respectively. 

NOTE 

All registers except RO are preserved 
across a programmed request. (In 
certain cases, RO may contain 
information passed back by the monitor; 
however, unless the description of a 
request indicates that a specific value 
is returned in RO, it may be assumed 
that the contents of RO are 
unpredictable upon return from the 
request). With the exception of calls to 
the CSI, the position of the stack 
pointer is also preserved across a 
programmed request. 
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9.2 SYSTEM CONCEPTS 

Some basic operational characteristics and concepts of RT-11 are 
described below. 


9.2.1 Channel Number (chan) 

A channel number is a logical identifier in the range 0 to 377(octal) 
for a file or "set of data" used by the RT-11 monitor. Thus, when a 
file is opened on a particular device, a channel number is assigned to 
that file. To refer to an open file, it is only necessary to refer to 
the appropriate channel number for that file. 


9.2.2 Device block (dblk) 

A device block is a four-word block of radix-50 information which 
specifies a physical device and file name for an RT-11 programmed 
request. (Refer to Chapter 5 for an explanation of .RAD50 strings.) 
For example, a device block representing a file FILE.EXT on device DK: 
could be written as: 

.RAD50 /DK / 

.RAD50 /FIL/ 

.RAD50 /E / 

.RAD50 /EXT/ 

The first word contains the device name, the second and third words 
contain the file name, and the fourth contains the extension. Device, 
name, and extension must each be left-justified in the appropriate 
field. This string could also be written as: 

.RAD50 /DK FILE EXT/ 

Note that spaces must be used to fill out each field. Note also that 
the colon and period separators do not appear in the actual RAD50 
string. They are used only by the monitor keyboard interface to 
delimit the various fields. 


9.2.3 EMT Argument Blocks 

Programmed requests which call the monitor via EMT 375 use RO as a 
pointer to an argument list. In general, this argument list appears 
as follows: 


address 

contents 


Function Channel 

X 

Code Number 

x+2 

argument1 

x+4 

argument2 

• 

• 

• • 

• • 
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RO points to location x. The even (low-order) byte of location x 
contains the channel number named in the macro call. If no channel 
number is required, the byte is set to 0. The odd (high-order) byte of 
x is a code specifying the function to be performed. Locations x+2, 
x+4, etc. contain arguments to be interpreted. These are described 
in detail under each request. 

Requests which use EMT 374 set up RO with the channel number in the 
even byte and the function code in the odd byte. They require no 
other arguments. 


9.2.4 Important Memory Areas 


9.2.4.1 Vector Addresses (0-37, 60-477) - Certain areas of memory 
between 0 and 477 are reserved for use by RT-11. KMON does not load 
these locations from the save image file when it initiates a program, 
i.e., R, RUN, and GET will not load these words. However, no hardware 
memory protection is supplied. Thus, programs should never alter the 
contents of the indicated areas at run-time. 

Locations Contents 


CM 

% 

O 

Monitor restart. Executes .EXIT 

returns control to KMON. 

request 

and 

4,6 

Time out 
point to 

or bus error trap; RT-11 
its internal trap handler. 

sets 

this 

to 

10,12 

Reserved 
point to 

instruction trap? RT-11 

its internal trap handler. 

sets 

this 

to 


30,32 EMT trap vector and status. 

40-57 RT-11 system communication area (see below). 

60,62 TTY input interrupt vector and status. 

64,66 TTY output interrupt vector and status. 

100,102 KWllL vector and status. 

204,206 RF11 vector and status. 

214,216 TC11 vector and status. 

220,222 RK05 vector and status. 

330,332 GT40 shift out interrupt vector and status. 

These areas are not replaced by RT-11. If they are destroyed by a 
program, the system must be re-bootstrapped, or the program must 
restore them. 
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9.2.4.2 Resident Monitor - Section 2.4 of Chapter 2 describes the 
placement of monitor components when either the Single-Job Monitor or 
F/B Monitor is brought into memory; included is the approximate size 
of each monitor component and the size of the area available for 
handlers and user programs. 


9.2.4.3 System Communication Area - RT-11 uses bytes 40-57 to hold 
information about the program currently executing, as well as certain 
information used only by the monitor. A description of these bytes 
follows: 


Bytes Meaning and Use 

40,41 Start address of job. When a file is linked into 

an RT-11 memory image, this word is set to the 
starting address of the job either with the Linker 
/T switch or as an argument in the .END statement 
of the program. When a foreground program is 

executed, the FRUN processor relocates this word 
to contain the actual starting address of the 
program. 

42,43 Initial value of the stack pointer. If it is not 

set by the user program in an .ASECT, it defaults 
to 1000 or the top of the .ASECT in the 
background, whichever is larger. If a foreground 
program does not specify a stack pointer in this 
word, a default stack (128 decimal words) is 
allocated by FRUN immediately below the program. 
The initial stack pointer can also be set with the 
Linker /M switch option. 

44,45 Job Status Word. Used as a flag word for the 

monitor. Certain bits are maintained by the 
monitor exclusively while others must be set or 
cleared by the user job. Those bits in the 
following list which are marked by an asterisk are 
bits which must be set by the user job. 

Since the currently unassigned bits may be used in 
future releases of RT-11, user programs should not 
use these bits for internal flags. 

Bit 

Number Meaning 

15 USR swap bit. (Unused in F/B.) The 

monitor sets this bit when programs do 
not require the USR to be swapped. See 
Section 9.2.5 for details on USR 

swapping. 

14 Lower-case bit. When set (automatically 

by EDIT when the EL command is typed), 
disables conversion of lower-case to 

upper-case. 

*13 Reenter bit. When set, this bit 

indicates that the program may be 
restarted from the terminal with the 
REENTER command. 
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l 


*12 Special mode TT bit. When set, this bit 

indicates that the job is in a "special" 
keyboard mode of input. Refer to the 
explanation of the .TTYIN/.TTINR 
requests for details, 

11-10 For F/B Monitor use only, 

9 Overlay Bit, Set (by the Linker) if the 

job uses the Linker overlay structure, 

8 CHAIN bit. If this bit is set in a 

job's save image, words 500-776 are 
loaded from the save file when the job 
is started even if the job is entered 
via CHAIN. (These words are normally 
used to pass parameters across CHAINS.) 
The bit is set when a job is running if 
and only if the job was actually entered 
with CHAIN. 

*7 Error halt bit. When set, this bit 

indicates a halt on an I/O error. If 
the user desires to halt when any I/O 
device error occurs, this bit should be 
set. (Unused in F/B.) 

*6 Inhibit TT wait bit. For use with the 

Foreground/Background system. When set, 
this bit inhibits the monitor from 
entering a console terminal wait state. 
Refer to the sections concerning 
.TTYIN/.TTINR, and .TTYOUT/.TTOUTR for 
more information. 

5-0 Unused. 

46,47 USR load address. Normally 0, this word may be 

set to any valid word address in the user's 
program. See Section 9.2.5, Swapping Algorithm, 
for details of use. 

50,51 High memory address. The monitor maintains the 
highest address the user program can use in this 
word. The Linker sets it initially. It is 
modified only via the .SETTOP (Set Top of Memory) 
monitor request. 

52 EMT error code. If a monitor request results in 

an error, the code number of the error is always 
returned in byte 52 and the carry bit is set. Each 
monitor call has its own set of possible errors. 
It is recommended that the user program reference 
byte 52 with absolute addressing, rather than 
relative addressing. For example: 

ERRWRD =52 

TSTB ERRWRD ;RELATIVE ADDRESSING 

TSTB @#ERRWRD ;ABSOLUTE ADDRESSING 
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NOTE 


Location 52 must always be addressed as 
a byte, never as a word, since byte 53 
will be used in future releases of 
RT-11. 

Reserved for future system use. 

Address of the beginning of the Resident Monitor. 
RT-11 always loads the resident into the highest 
available memory locations; this word points to 
its first location. It must never be altered by 
the user. Doing so will cause RT-11 to 
malfunction. 

Fill character (7-bit ASCII). Some high-speed 
terminals require filler (null) characters after 
printing certain characters. Byte 56 should 
contain the ASCII 7-bit representation of the 
character after which fillers are required. 

Fill count. This byte specifies the number of 
fill characters required. If bytes 56 and 57=0, 
no fillers are required. 

The required fill characters are: 


Value of 

Terminal No. of fills Word 56 


Serial 

LA30 

@ 

300 

baud 

10 

after carriage return 

5015 

Serial 

LA30 

@ 

150 

baud 

4 

after carriage return 

2015 

Serial 

LA30 

@ 

110 

baud 

2 

after carriage return 

1015 

VT05 


@ 

2400 

baud 

4 

after line feed 

2012 

VT05 


@ 

1200 

baud 

2 

after line feed 

1012 

VT05 


@ 

600 

baud 

1 

after line feed 

412 


9.2.5 Swapping Algorithm 

Programmed requests are divided into two categories according to 
whether or not they require the USR to be in memory (see Table 9-2). 
Any request which requires the USR in memory may also require that a 
portion of the user program be saved temporarily on the system device 
scratch blocks (i.e., be "swapped out") to provide room for the USR. 
The USR will be read into the swapped region. 

During most normal operations, this swapping is invisible to the user 
and he need not be concerned about it. However, it is possible to 
optimize programs so that they require little or no swapping. This is 
particularly useful when operating in an F/B environment, since under 
the F/B system, the USR will be swapped for both background and 
foreground jobs regardless of which job required it. If the USR is 
not swapped, neither the foreground nor the background job will be 
slowed down by the swapping process. 

The following items should be considered if a swap operation is 
necessary: 

1. The background job - If a .SETTOP request in a background job 
specifies an address beyond the point at which the USR 


53 

54,55 


56 


57 
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normally resides, a swap will be required when the USR is 
called. More details concerning the .SETTOP request are in 
Section 9.4.36. 

2. The value of location 46 - If the user either assembles an 
address into word 46 or moves a value there while the program 
is running, RT-11 uses the contents of that word as an 
alternate place to swap the USR. If location 46 is 0, this 
indicates that the USR will be at its normal location in high 
memory. 

NOTES 

1. If the USR does not require 
swapping, the value in location 46 
is ignored. Swapping is a 
relatively time-consuming operation 
and is avoided, if possible. 

2. A foreground job should always have 
a value in location 46 unless it is 
certain that the USR will never be 
swapped. If the foreground job does 
not allow space for the USR and a 
swap is required, a fatal error 
occurs. (The SET USR NOSWAP 
command, explained in Chapter 2, 
ensures that the USR will be 
resident.) 

3. Care should be taken when specifying 
an alternate address to location 46. 

The single-job system does not 
verify the legality of the USR swap 
address. Thus, if the area to be 
swapped overlays the Resident 
Monitor, the system is destroyed. 

4. The user should also take care that 

the USR is never swapped over any of 
the following areas: the program 

stack; any parameter block for 
calls to the USR; any I/O buffers, 
device handlers, or completion 
routines being used when the USR is 
called. 


The following is an example of the way a background program can avoid 
unnecessary USR swapping. 


.mcalu 

• • v 2 • . 

.HtGDEF 

RMPTR«5« 

USPL0C«26t> 

START: 

MOV 

MOV 

TST 


..V*..,.»EP0FF,.SETTOP,.FXTT 

t POINTER TO RMON I* AT 5«. 

;POINTER TO USR LOCATION IS 
IAT BYTES INTO RMON. 

##PMPTR,R1 »Rt -> RESIDENT MONITOR 

USRlOC(R l)#R0 ;ro -> USP 

-CRtf) »P0INT JUST BELOW 
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CMP 

BHA )$ 

MOV #-S,Rp 

IS* .StTTOP 

M Q V B0.HILIM 

.E*IT 

HIlIMj ,*URD PI 

.END START 


IOOES USB SWAP OVER US? 

INO, OK 

»VFS. USB MUST SWAP 
>ASk FOR MFMORY lip TO IJSB 

;Be> 8 high limit of memory 
/ACTUALLY GRANTED BY monitor 

/CONTAINS hi LIMIT of memory 


9.2.6 Offset Words 

the 16 qri- S nf 6 fh 1 ”° r< ? a which f lwa Y s have fixed positions relative to 
tr! J th . e . Re f ldent Monitor. It is often advantageous for user 
cod! fc bS 31,16 tD access these words. This is done with the 


RMON = 54 

MOV @#RMON r register 

MOV OFFSET(register)^register 

followin^lilt- 18 ^ general re 9 ister ^ OFFSET is a number from the 


OFFSET (Bytes) Contents 

262 System date. (See .DATE request.) 

266 Start of normal USR area. This is where the 

USR will reside when it is non-swapping. It 
is useful to be able to perform a .SETTOP in 
a background job such that the USR is always 
resident. (An example is in Section 9.2.5.) 


270 


275 

276 

277 


Address of I/O exit routine for all devices. 
The exit routine is an internal queue 
management routine through which all device 
handlers exit once the I/O transfer is 
complete. Any new devices added to RT-11 
must also use this exit location. 


Unit number of system device (device from 
which system was last bootstrapped). 

Monitor version number (2-377). The user can 
always access the version number to determine 
if the most recent monitor is in use. 


Update number. Patches to the monitor always 
increment the update number. This provides a 
means of checking that all patches have been 
made. (This number should be accessed bv 
MOVB rather than MOV). 


Configuration word. This is a string of 16 
bits used to indicate information about 
either the hardware configuration of the 
system, or a software condition. The bits 
and their meanings are: 
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i 


304-313 


314 


324 


354 


Bit # 


Meaning 


0 

2 

3 

5 

6 

7 

8 
9 

11 

15 


0 

1 

1 

1 

0 

1 

1 

0 

1 

1 

1 

1 

1 


Single-Job Monitor 
F/B Monitor 

GT40 display hardware exists 
RT-11 BATCH is in control 
of the background 
60-cycle clock 
50-cycle clock 
11/45 floating-point 
hardware exists 

No foreground job is in memory 
Foreground job is in memory 
User is linked to the GT40 


scroller 

USR is permanently resident 


(via a SET USR NOSWAP) 

Processor is an 11/03 


KW11L clock is present 

(always set if 11/03) 


The other bits are reserved for future use 
and should not be accessed by user programs. 


These locations contain the addresses of the 
console terminal control and status 
registers. The order iss 


304 Keyboard status 
306 Keyboard buffer 
310 Printer status 
312 Printer buffer 


These locations can be changed, for example, 
to reflect a second terminal; thus RT-11 can 
be made to run on any terminal present on the 
system which is connected to the machine via 
the DLll multiple terminal interface. (Refer 
to the RT-11 Software Support Manual 
(DEC—11—ORPGA—B—D). 


The maximum file size allowed in a 0 length 
.ENTER. This can be adjusted by the user 
program or by using the PATCH program to be 
any reasonable value. The default value is 
177777 (decimal) blocks, allowing an 
essentially unlimited file size. 


Address of .SYNCH entry. User interrupt 
routines may enter the monitor through this 
address to synchronize with the job they are 
servicing. 


Address of VTll display processor display 
stop interrupt vector. 
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9.2.7 Pile Structure 

RT-11 uses a "contiguous" file structure. This type of structure 
implies.that every file on the device is made up of a contiguous group 
of physical blocks. Thus, a file that is 9 blocks long occupies 9 
contiguous blocks on the device. 

A contiguous area on a device can be in one of the following 
categories s 

1. Permanent file. This is a file which has been .CLOSEd on a 
device. Any named files which appear in a PIP directory 
listing are permanent files. 

2. Tentative file. Any file which has been created via .ENTER, 
but not .CLOSEd, is a tentative file entry. When the .CLOSE 
request is given, the tentative entry becomes a permanent 
file. if a permanent file already exists under the same 
name, the old file is deleted. If a .CLOSE is never given, 
the tentative file is treated like an empty entry. 

3. Empty entry. When disk space is unused or a permanent file 
is deleted, an empty entry is created. Empty entries appear 
in a PIP /E directory listing as <UNUSED> N, where N is the 

decimal block length of the empty area. 

Since a contiguous structure does not automatically reclaim unused 
disk space, the device may eventually become "fragmented". A device is 
fragmented when there are many empty entries which are scattered over 
the device. RT-11 PIP has an option which allows the user to collect 
all empty areas so that they occur at the end of a device. Refer to 
Chapter 4 for details. 


9.2.8 Completion Routines 


Completion routines are user-written routines which are entered 
following an operation. On entry to a completion routine, RO contains 
the channel status word for the operation; R1 contains the octal 
channel number of the operation. The carry bit is not significant. 


Completion routines are handled differently in the Single-Job and the 
F/B versions of RT-11. in the Single-Job version, completion routines 
are totally asynchronous and can interrupt one another. In F/B, 
completion routines do not interrupt each other. Instead they are 

mlp and if ade f t ° wait . the correct job is running. * For 
example, if a foreground job is running and an I/O transfer initiated 
by a background job completes and wants to go to a completion routine, 
the background routine is queued and will not execute until the 
foreground gives up control of the system. if the foreground is 
running and a foreground I/O transfer completes and wants a completion 
routine, that routine will be entered immediately if the foreground is 
not aiready inside a completion routine. If it is in a completion 
routine, that routine continues to termination, at which point any 

K 0m v 2 irOUtinea are entered in a first in/first out manner. 
*5. the background is running and a foreground I/O transfer completes 
and needs a completion routine, the background is suspended and the 
foreground routine is entered immediately. 
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Die restrictions which must be observed when writing completion 
routines are: 

1. Completion functions cannot issue a request which would cause 
the USR to be swapped in. They are primarily used for 
issuing READ/WRITE commands, not for opening or closing 
files, etc. A fatal monitor error is generated if the USR is 
called from a completion routine. 

2. Completion routines should never reside in the memory space 

which will be used for the USR, since the USR can be 

interrupted when I/O terminates and the completion routine is 
entered. If the USR has overlaid the routine, control 
passes to a random place in the USR, with a HALT or error 
trap the likely result. 

3. The routine must be exited via an RTS PC, as it is called 

from the monitor via a JSR PC,ADDR where ADDR is the 

user-supplied address. 

4. If a completion routine uses registers other than RO or Rl, 
it must save them upon entry and restore them before exiting. 


9.2.9 Using the System Macro Library 

User programs for RT-11 should always be written using the system 
macro library (SYSMAC.SML) , supplied with RT-11. This ensures 
compatibility among all user programs and allows easy modification oy 
redefining a macro. A listing of SYSMAC.SML appears in Appendix D. 

The system macro library for 8K systems appears on the system device 
as SYSMAC.8K. 

Suggestions for writing foreground programs are in Appendix H, F/B 
Programming and Device Handlers. This appendix should be read in 
conjunction with Chapter 9 before coding F/B programs. 


9.3 TYPES OF PROGRAMMED REQUESTS 

There are three types of services which the monitor makes available to 
the user through programmed requests. These ares 

1. Requests for File Manipulation 

2. Requests for Data Transfer 

3. Requests for Miscellaneous Services 

Table 9-1 summarizes the programmed requests in each of these 
categories alphabetically. Those marked with an asterisk function 
only in a F/B environment; they are ignored under the Single-Job 
Monitor. The EMT and function code for each request (where 

applicable) are included. 
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Table 9-1 

Summary of Programmed Requests 


Mnemonic 

EMT & 
Code 

Section 

Purpose 

File Manipulation Requests 

*.CHCOPY 

375 

13 

9.4.3 

Establishes a link and allows one 
job to access another job's 
channel. 

.CLOSE 

374 

6 

9.4.4 

Closes the specified channel. 

.DELETE 

375 

0 

9.4.10 

Deletes the file from the specified 
device. 

.ENTER 

375 

2 

9.4.13 

Creates a new file for output. 

.LOOKUP 

375 

1 

9.4.21 

Opens an existing file for input 
and/or output via the specified 
channel. 

.RENAME 

375 

4 

9.4.32 

Changes the name of the indicated 
file to a new name. 

.REOPEN 

375 

6 

9.3.33 

Restores the parameters stored via 
a SAVESTATUS request and reopens 
the channel for I/O. 

.SAVESTATUS 

375 

5 

9.4.34 

Saves the status parameters of an 
open file in user memory and frees 
the channel for future use. 

Data Transfer Requests 

*.RCVD 
*.RCVDW 
*.RCVDC 

375 

26 

9.4.29 

Receives data. Allows a job to 
read messages or data sent by 
another job in an F/B environment. 
The three modes correspond to the 
READ, .READC, and READW modes. 

.READ 

375 

10 

9.4.30 

Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
when the transfer request is 
entered in the I/O queue. No 
special action is taken upon 
completion of I/O. 

.READC 

375 

10 

9.4.30 

Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
when the transfer request is 

entered in the I/O queue. Upon 

completion of the read, control 
transfers asynchronously to the 

routine specified in the .READC 
request. 
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Programmed Requests Table 9-1 (Cont.) 

Summary of Programmed Requests 


Mnemonic 

EMT & 
Code 

Section 

Purpose 

.READW 

375 

10 

9.4.30 

Transfers data via the specified 
channel to a memory buffer and 
returns control to the user program 
only after the transfer is 
complete. 

*.SDAT 
*.SDATC 
*.SDATW 

375 

25 

9.4.35 

Allows the user to send messages or 
data to the other job in an F/B 
environment. The three modes cor¬ 
respond to the .WRITE, .WRITC and 
.WRITW modes. 

.TTYIN 

.TTINR 

340 

— 

9.4.43 

Transfers one character from the 

keyboard buffer to R0. 

.TTYOUT 
•TTOUTR 

341 

— 

9.4.44 

Transfers one character from R0 

to the terminal input buffer. 

.WRITE 

375 

11 

9.4.47 

Transfers data via the specified 
channel to a device and returns 
control to the user program when 
the transfer request is entered in 
the I/O queue. No special action 
is taken upon completion of the 
I/O. 

.WRITC 

375 

11 

9.4.47 

Transfers data via the specified 
channel to a device and returns 
control to the user program when 
the transfer request is entered in 
the I/O queue. Upon completion of 
the write, control transfers 
asynchronously to the routine 
specified in the .WRITC request. 

.WRITW 

375 

11 

9.4.47 

Transfers data via the specified 
channel to a device and returns 
control to the user program only 
after the transfer is complete. 

Miscellaneous Services 

.CDFN 

375 

15 

9.4.1 

Defines additional channels for 

doing I/O. 

.CHAIN 

374 

10 

9.4.2 

Chains to another program (in the 
background job only)• 

*.CMKT 

375 

23 

9.4.5 

Cancels an unexpired mark time 

request. 

*.CNTXSW 

375 

33 

9.4.6 

Requests that the indicated memory 
locations be part of the F/B 
context switch process. 

.CSIGEN 

344 

— 

9.4.7 

Calls the Command String 

Interpreter (CSI) in general mode. 

.CSISPC 

345 

— 

9.4.8 

Calls the CSI in special mode. 
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Programmed Requests Table 9-1 (Cont.) 

Summary of Programmed Requests 


Mnemonic 

EMT & 
Code 

Section 

Purpose 

*.CSTAT 

37! 

27 

9.4.9 

Returns the status of the channel 
indicated. 

.DATE 


• —— 

9.3.1.1 

Moves the current date information 
into R0. 

*.DEVICE 

375 

>14 

9.4.11 

Allows user to turn off device 
interrupt enable in F/B upon 
program termination. 

.DSTATUS 

342 

— — 

9.4.12 

Returns the status of a particular 
device. 

.EXIT 

350 


9.4.14 

Exits the user program and returns 
control to the Keyboard Monitor. 

.FETCH 

343 


9.4.15 

Loads device handlers into memory. 

• GTIM 

375 

21 

9.4.16 

Gets time of day. 

.GTJB 

375 

20 

9.4.17 

Gets parameters of this job. 

.HERR 

374 

5 

9.4.18 

Specifies termination of the job on 
fatal errors. 

.HRESET 

357 

“ 

9.4.19 

Terminates I/O transfers and does a 
.SRESET operation. 

.INTEN 



9.3.1.2 

Notifies monitor that an interrupt 
has occurred and to switch to 
"system state", and sets the 
processor priority to the correct 
value. 

.LOCK 

346 


9.4.20 

Makes the monitor User Service 
Routines (USR) permanently resident 
until .EXIT or .UNLOCK is executed. 
The user program is swapped out if 
necessary. 

• MFPS 



9.3.1.3 

Reads the priority bits in the 
processor status word (does not 
read the condition codes). 

*.MRKT 

375 

22 

9.4.22 

Marks time; i. e ., sets 
asynchronous routine to occur after 
a specified interval. 

. MTPS 


— 

9.3.1.3 

Sets the priority bits, condition 
codes, and T bit in the processor 
status word. 

*.MWAIT 

374 

11 

9.3.23 

Waits for messages to be processed. 

.PRINT 

351 


9.4.24 

Outputs an ASCII string to the 
terminal. 

*.PROTECT 

375 

31 

9.4.25 

Requests that vectors in the area 
from 0-476 be given exclusively to 
this job. 
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Table 9-1 (Cont.) 


Mnemonic * 

:mt & s 

Code 

ection 

Purpose 

.PURGE 

374 

3 9 

1.4.26 

Clears out a channel# 

.QSET 

353 - 

— s 

>.4.27 

Expands the size of the monitor I/O 
queue. 

.RCTRLO 

.REGDEF 

355 - 

_ ( 

... 

).4.28 

>.3.1.4 

Enables output to the terminal. 

Defines the PDP-11 general 

registers. 

.RELEAS 

343 


9.4.31 

Removes device handlers from 

memory. 

*.RSUM 

374 

2 

9.4.39 

Causes the main line of the job to 
be resumed where it was suspended 
with .SPND. 

.SERR 

374 

4 

9.4.18 

Inhibits most fatal errors from 
causing the job to the aborted. 

.SETTOP 

354 

— 

9.4.36 

Specifies the highest memory 

location to be used by the user 





program. 

.SFPA 

375 

30 

9.4.37 

Sets user interrupt for floating 
point processor exceptions. 

.SPFUN 

375 

32 

9.4.38 

Performs special functions on 

magtape and cassette units. 

* . SPND 

374 

1 

9.4.39 

Causes the running job to be 

suspended. 

,SRESET 

352 

— 

9.4.40 

Resets all channels and releases 
the device handlers from memory. 

.SYNCH 


— 

9.3.1.5 

Enables user program to perform 
monitor programmed requests from 
within an interrupt service 
routine. 

*.TLOCK 

374 

7 

9.4.41 

Indicates if the USR is currently 
being used by another job and 
performs a .LOCK if available. 

.TRPSET 

375 

; 3 

9.4.42 

Sets a user intercept for traps to 
locations 4 and 10. 

*.TWAIT 

375 

> 24 

9.4.45 

Suspends the running job for a 
specified amount of time. 

.UNLOCK 

34‘ 

7 “ 

9.4.20 

Releases USR if a LOCK was done. 
The user program is swapped in if 
required. 

| ..VI.. 

— 


9.3.1.6 

Enables expansions to occur in 

Version 1 format. 

| ..V2.. 

— 


9.3.1.6 

Enables expansions to occur in 

Version 2 format. 

.WAIT 

37 

4 0 

9.4.46 

Waits for completion of all I/O on 
a specified channel.____ 
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Table 9-2 

Requests Requiring the USR 


Request 

F/B 

Single-Job 

*.CDFN 

No 

Yes 

*.CHAIN 

No 

No 

*.CHCOPY 

No 

N/A 

.CLOSE (see Note 1) 

Yes 

Yes 

*.CMKT 

No 

N/A 

*.CNTXSW 

No 

N/A 

.CSIGEN 

Yes 

Yes 

.CSISPC 

Yes 

Yes 

*.CSTAT 

No 

N/A 

.DELETE 

Yes 

Yes 

*.DEVICE 

No 

N/A 

.DSTATUS 

Yes 

Yes 

.ENTER 

Yes 

Yes 

.EXIT 

No 

No 

.FETCH 

Yes 

Yes 

*.GTIM 

No 

No 

*.GTJB 

No 

No 

*.HERR 

No 

No 

.HRESET 

No 

Yes 

.LOCK (see Note 2) 

Yes 

Yes 

.LOOKUP 

Yes 

Yes 

*.MRKT 

No 

N/A 

*.MWAIT 

No 

N/A 

.PRINT 

No 

No 

*.PROTECT 

No 

N/A 

♦.PURGE 

No 

No 

.QSET 

Yes 

Yes 

.RCTRLO 

No 

No 

*.RCVD/RCVDC/RCVDW 

No 

N/A 

. READ/READC/.READW 

No 

No 

.RELEAS 

Yes 

Yes 

.RENAME 

Yes 

Yes 

.REOPEN 

No 

No 

*.RSUM 

No 

N/A 

.SAVESTATUS 

No 

No 

*.SDAT/S DATC/S DATW 

No 

N/A 

*.SERR 

No 

No 

.SETTOP 

No 

No 

*.SFPA 

No 

No 

*.SPFUN 

No 

No 

*.SPND 

No 

N/A 

*.SRESET 

No 

Yes 

*.TLOCK (see Note 3) 

No 

No 

♦.TRPSET 

No 

No 

.TTINR/.TTYIN 

No 

No 

.TTOUTR/.TTYOUT 

No 

No 

*.TWAIT 

No 

N/A 

.UNLOCK 

No 

NO 

.WAIT 

No 

NO 

.WRITE/WRITC/WRITW 

No 

No 
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Note 1: Only if channel was opened via .ENTER. 

Note 2: Only if USR is in a swapping state. 

Note 3: Only if USR is not in use by the other job. 


9.3.1 System Macros 

The following five macros are included in the system macro library, 
but are not programmed requests in that they cause no EMT instruction 
to be generated: 

.DATE .SYNCH 

.INTEN ..V2.. 

.REGDEF 

They can be used in the same manner as the other macro calls; their 
explanations follow. 


.DATE 


9.3.1.1 .DATE 

This request moves the current date information from the system date 
word into RO. The date word returned is in the following format: 

Bit: 14 10 9 54 0 



MONTH 

DAY 

YEAR-72(DECIMAL) 


(1-12.) 

(1-31.) 



Macro Call: .DATE 

Errors: 

No errors are returned. A zero result in RO indicates that no DATE 
command was entered. 
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.INTEN 

9.3.1.2 .INTEN 

This request is used by user program interrupt service routines to: 

1. Notify the monitor that an interrupt has occurred and to 
switch to "system state", 

2. Set the processor priority to the correct value. 


V t^ S1 ? n 2 i°t ? T-11 ' a11 external interrupts cause the processor to 
4-u 1 ? VSl Z <see^Appendix H) . .INTEN is used to lower the priority 

InSn Va Zh« a a W ^ 1 device should be run. On return from 

.INTEN, the device interrupt can be serviced, at which point the 

that rr an returns via an RTS PC. It is very important to note 

“Joten? r " correot1 '' fr °” “> interrupt routine which 


Macro Call: .INTEN .priority, pic 


where: .priority is the processor priority at which the user 

wishes to run his interrupt routine. 


plc is an optional argument which should be 

non-blank if the interrupt routine is written 
as a PIC (position independent code) routine. 
If the routine does not have to be PIC, it is 
recommended that the PIC field be left blank; 
the non—PIC version is slightly faster than 
the PIC version. 


The user is advised to read Appendix H for more details 
use of .INTEN and .SYNCH. 


concerning the 


Errors: 
None. 


Example; 

Refer to Section 9.3.1.5, .SYNCH, for an example. 
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.MFPS/.MTPS 


9.3.1.3 .MFPS/.MTPS 

The .MFPS and .MTPS macro calls allow processor-independent user access 
to the processor status word. 

The .MFPS call is used to read the priority bits only; condition codes 
are destroyed during the call and must be directly accessed (using con¬ 
ditional branch instructions) if they are to be read in a processor 
independent manner. 

Macro Call: .MFPS .addr 

where: .addr is the address into which the processor status 

is to be stored; if .addr is not defined, the 
value is returned on the stack. Note that only 
the priority bits are significant. 

The .MTPS call is used to set the priority, condition codes, and T bit 
with the value designated in the call. 

.MTPS .addr 

.addr is the address of the word to be placed in the 

processor status word; if .addr is not defined, 
the processor status word is taken from the 
stack. Note that the high byte on the stack is 
set to zero when .addr is present. If .addr is 
not present, the user should set the stack to 
the appropriate value. In either case, the 
whole word on the stack is put in the processor 
status word. 

The contents of RO are preserved across either call. 

Errors: 

None. 


Macro Call: 
where: 
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Example: 


• MC *LL ••V?,.,,REGDEE,.MEP$,,MTPS,.EXIT 

• ■ Vg.. 

.REGDEE 

5T*RT» JSR PC,PICKQ fPICK A QUEUE ELEMENT 


.EXIT 

PICKQI ,MFP5 

MOV #QHEAO»RU 

•MTPS #3A0 

MOV #R«,R5 

BEQ 10S 

MOV *R5,PRA 

.MTPS 

CL2 

10$I RTS PC 
QHEADt .WORD 01 

ithree queue elements 

Oil .WORD OS,0,0 

Q2» .WORD 03,0,0 

Q3t .WORD 0,0,0 

.END START 


ISAVE PREVIOUS PRIORITY IN 
I POINT TO QUEUF HEAD 
»RAISE PRIORITY TO 7 
IRS POINTS TO NEXT ELEMENT 
INO MORE ELEMENTS AVAILABLE 
IRELINK THE QUEUE 
IRESTORE PREVIOUS PRIORITY 
I FLAG SUCCESS 

I QUEUE HEAD 


SP 
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.REGDEF 


9.3.1.4 .REGDEF 

This macro call defines the PDP-11 general registers as RO through R5, 
SP, and PC. 

Macro Call: .MCALL .REGDEF,... 

.REGDEF 

Errors: 

None. 

Example: 

Refer to the example for the .SYNCH request. Appendix D shows the 
expansion of .REGDEF. 


.SYNCH 


9.3.1.5 .SYNCH 

This macro call enables the user program to perform ^nitor pro^ammed 
requests from within an interrupt service routine. Unless a .SYNCH is 
used, issuing programmed requests from interrupt routines is not 
supported by the system and should not be performed. * S ™CH, like 
.INTEN and .DATE, is not a programmed request and generates no 
EMT instructions. 


Macro Call: 


.SYNCH .area 


where: .area 


is the address of a seven-word area which the 
user must set aside for use by .SYNCH. The 
7-word block appears as: 


Word 1 RT-11 maintains this word; its 

contents should not be altered by 
the user. 

Word 2 The current job*s number. This can 
be obtained by a .GTJB call. 

Word 3 Unused. 
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Word 4 Unused. 

Word 5 RO argument. When a successful 
return is made from .SYNCH, RO 
contains this argument. 

Word 6 Must be -1. 

Word 7 Must be 0. 


Notes 


.SYNCH assumes that the user has not 
between the .INTEN and .SYNCH calls 
proper operation. 


pushed anything on the stack 
This rule must be observed for 


Errors s 


The monitor returns to the location immediately following the .SYNCH 
xf the .SYNCH was rejected. The routine is still unable to issue 
programmed requests, and R4 and R5 are available for use. Errors 
returned are due to one of the followings 


1. Another .SYNCH which specified the same 7—word block is still 
pending. 


2. An illegal job number was specified in the second word of the 
block. The only currently legal job numbers are 0 and 2. 

3. If the job has been aborted or for some reason is no lonqer 
running, the .SYNCH will fail. 

Normal return is to the word after the error return with the routine 
in user state and thus allowed to issue programmed requests. RO 
contains the argument which was in word 5 of the block. RO and R1 are 
free to be used without having to be saved. (R4 and R5 are not free ) 
Exit from the routine should be done via an RTS PC. (Refer to Appendix 
H, Section H.1.4, and to the RT-11 Software Support Manual. 
Section 6.4.) --- 


Example: 


9TART| 


.mcall 

. • v 2., 

.REGOEE 

.MCALL 

MOV 

.GTJB 

mqv 


.RE8DFP 


•GTJM,.INTFN,.WRITr,.SYNCH,.EXIT,,PR TNT 
•JOB,RB (OUTPUT OF .GT JB GOES HERE 

•ABEA.R5 (GET JOB NUMBER 

(RE),SYNBLK*E (STORE THE JOB NUMBER TNTO SYNCH BLOCK 
(IN HERE WE set UR INTERRUPT 
(PROCESSING, AND START UP THE 
(INTERRUPTING ogVICE’. 


TNTRPfI .INTEN 9 


.synch rsynblk 

BR SYNEAIL 


(GO INTO SYSTEM STATE 
(RUN AT LEVEL EJVE 
(INTERRUPT PROCESSING -- 
(NOTHING CAN GO ON STACK 
ITJME TO .WRITE A BUFEER 
(SYNCH BLOCK IN USE 
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I RETURN HfRC AT PRTORITY 0‘. NBTFl .SYNCH B0E8 RTJ 


.WRITC 

BCS 


RAPE A, CHAN, B'JFF ,WCNT,#CRTN1 ,ALK 
iwpjte A buffer 


WTRATL 


>F»ILEr> SOMEHOW 


RTS PC 

SYNBLKi ,W 0 R 0 fl 

.WORD P 
,WORD P 
.WORD P 
,WORB B 

’.WORD -1,0 
SYNFAIU* 


FRF-TNTT1ALITE FOR MORE 
tINTERRUPTS ‘NO EXIT 

>JOB NUMBER 


IRP CONTAINS 5 ON SUCCESSFUL 
ISVNCH 

t SFT UP FOR MONITOR 


..VI ../. .V2.. 


9.3.1.6 ..VI../..V2.. 

Any program that uses system MACROS must specify the version format 
(Version 1 or Version 2) in which the macro calls are to be expanded. 
Assembly errors at macro calls will result if the proper version 
designation is not made. 

The ..VI.. macro call enables all macro expansions to occur in Version 
1 format. (Note that any requests marked with an asterisk in Table 
9-1 are not valid as Version 1 requests, and thus will be flagged as 
errors if they are assembled in Version 1 form.) 


Macro Call: .MCALL ..Vl.. 

..VI.. 

This causes all macros in the program to be assembled in Version 1 

form and the symbol ...Vl to be defined. User programs should not use 
this symbol. The ..Vl.. macro expands into: 

...Vl=l 

To cause all macro expansions to occur in Version 2 format, the ..V2.. 
macro call is used. Using ..V2.. causes the symbol ...V2 to be 

defined. Likewise, user programs should not use thxs symbol. 


Macro Call: .MCALL ,.V2.. 

..V2.. 


The .,V2.. macro expands into: 

.MCALL ...CMl,-CM2,...CM3,-CM4 

...V2=l 
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Note: 


It is possible that user programs will exist in which both Version 1 

Y® r! ? 10 !? a m f^ ros are present. To allow proper assembly, the user 
should include the statements: 


.MCALL 

..VI.. 


•VI..,...CM1,...CM2,...CM3,...CM4 


to define the utility macros (CM1, CM2, etc.) used by other Version 2 
macros._ This causes all macros which existed in Version 1 to assemble 
m Version 1 format, while those macros new to Version 2 are correctly 
generated as Version 2 macros. Note that in this case a macro which 
existed in Version 1 (such as .READ) will expand in the Version 1 
format. 


Run-time or assembly errors will occur if both the ..VI.. and 
macro calls are used in a program. 


Example: 


All examples in Chapter 9 illustrate the Version 2 format. Users are 
urged to use the ..V2.. macro call in their programs. 


9.4 PROGRAMMED REQUEST USAGE 


This section provides a description of each of the programmed 
alphabetically. The following parameters are commonly 
arguments in the various calls: 


requests 
used as 


an address, the meaning of which depends on the 
request being used 


.area 

.blk 

.buff 


. chan 
.crtn 


.count 


a pointer to the EMT argument list (for those 
requests which require a list); see Section 9.2.3 

a block number specifying the relative block in a 
file where an I/O transfer is to begin 

a buffer address specifying a memory location into 
or from which an I/O transfer is to be performed 

a channel number in the range 0-377(octal) 

the entry point of a completion routine; see 
Section 9.2.8 

file number for magtape/cassette operations (see 
Appendix H); if this argument is blank, a value of 
0 is assumed 


.dblk 


. num 


.went 


the address of a four-word RAD50 descriptor of the 
file to be operated upon; see Section 9.2.2 

a number, the value of which depends on the 
request 

a word count specifying the number of words to be 
transferred to or from the buffer during an I/O 
operation 


Additional information concerning these parameters (and others 
defined here) is provided as necessary under each request. 
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.CDFN 


9.4.1 .CDFN 

The .CDFN request is used to redefine the number of I/O channels. 
Each job, whether foreground or background, is initially provided with 

16(decimal) I/O channels, numbered 0-15. .CDFN allows the number t 
be expanded to as many as 255(decimal) channels. 

Note that .CDFN defines new channels; the previously-defined channels 
are not used. Thus, a .CDFN for 20(decimal) channels (while the 16 
original channels are defined) causes only 20 I/O channels; the space 
for the original 16 is unused. 


Note that if a program is overlaid, channel 15 is used by the overlay 
handler and should not be modified. (Other channels can be defined and 
used as usual.) 


Macro Calls .CDFN .area, .addr, .num 


where: .addr 

.num 

Request Format: 


is the address where the I/O channels begin 
is the number of I/O channels to be created 


R0 =(► .areas 


15 0 


.addr 

.num 


The space used to contain the new channels is taken from within the 
user program. Each I/O channel requires 5 words of memory. Thus, the 
user must allocate 5*N words of memory, where N is the number of 
channels to be defined. 


It is recommended that the .CDFN request be used at the beginning of a 
program, before any I/O operations have been initiated. If more than 
one .CDFN request is used, the channel areas must either start at the 
same location or not overlap at all. The two requests .SRESET and 
.HRESET cause the user's channels to revert to the original 16 
channels defined at program initiation. Hence, any .CDFNs must be 
reissued after using those directives. 


Errors s 


Code Explanation 

0 An attempt was made to define fewer channels than 

already exist. 


Example: 

.HC A U L .•V2.,»•REGDEF 
t • V2,, 

.REGDEF 

,PCAIL .CDFN,.PRINT, .EXIT 


STARTS 

.CDFN 

•R0LIST,PCHANt,FA0, 


BCS 

BADCDF 


.PRINT 

iMSGi 

BADCOFl 

.EXIT 

.PRINT 

PNSG2 

HSG1I 

.EXIT 

.A8CIZ 

/.CDFN 0.K ,/ 

.EVEN 

M3G2S 

.A SC IZ 

/BAD .CDFN/ 

January 
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misn 

.EVEN 

.BUw 

3 

I6MT ARGUMENT LIST 

CHANLl 

• BLKm 

40,*5 

1 ROOM FOR CHANNELS 


.END 

3T ART 



The example defines 40 (decimal) channels to start at location CHANL, 
An error occurs if 40 or more channels are already defined. 
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.CHAIN 


9.4.2 .CHAIN 

This request allows a background program to pass control directly to 
another background program without operator intervention. Since this 
process may be repeated, a large "chain" of programs can be strung 


The area from locations 500-507 contains the device name and file name 
(in RAD50) to be chained to, and the area from locations 510-777 is 
used to pass information between the chained programs. 

Macro Call: .CHAIN 


Notes: 


1. No assumptions should be made concerning which areas of 
memory will remain intact across a .CHAIN. In general, 
500-777 is the only area guaranteed to be preserved across 
a .CHAIN. 


2. I/O channels are left open across a .CHAIN for use by the new 
program. However, I/O channels opened via a .CDFN request 
are not available in this way. Since the monitor reverts to 
to the original 16 channels during a .CHAIN, programs which 
leave files open across a .CHAIN should not use .CDFN. 
Furthermore, non-resident device handlers are released during 
a .CHAIN, and must be .FETCHed again by the new program. 


3. 


A program can determine whether it was CHAINed to or RUN from 
the keyboard by examining bit 8 of the JSW. This bit is on 
Program execution only if the program was entered via 
chain. If a program normally loads into area 500-777, bit 8 
of the JSW should be set during program assembly. This causes 
the monitor to load the area properly, if the bit is not set, 
locations 500-777 are preserved from the chaining program, 
-causing the new program to malfunction. 


Errors: 


.CHAIN is implemented by simulating the monitor RUN command (described 
in Chapter 2), and can produce any errors which RUN can produce. If 
an error occurs, the .CHAIN is abandoned and the Keyboard Monitor is 
entered. 


When using .CHAIN, care should be taken for initial stack placement, 
since the program being "chained to" is started. The Linker normally 
defaults the initial stack to 100Q(octal); if caution is not observed* 

Se S»to™Ldr? tr ° y Chaln date bef ° re U 156 " s * d <■“ 
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Example: 


ST ART I 


LOOP I 


CHPTR: 


,MCALL ,,V2,.,.PE60EF 
,.V2.. 

,REGDEF 

,MCALL .CHAIN,.TTYIN 


MOV 

#500,R1 

MOV 

•CHPTR,R2 

,REPT 

4 

MOV 
• ENOR 
.TTYIN 

(R2)♦»(R1)♦ 

MO VB 

R0,(Rl)* 

CMPB 

R0» #12 

BNE 

LOOP 

CLRB 

.CHAIN 

CRD* 

.RAD50 

/OK / 

.RAO50 

/TECO t 

.RAD50 

/ SAV/ 

.END 

START 


I SET UP TO CHAIN 

(DEVICE, FILE NAME TO 500-511 


INOM GET A COMMAND LINE 
(AND PASS IT TO THE JOB 
I IN LOCATIONS 512 AND UP 
I LOOP UNTIL LINE FEED 
I PUT IN A NULL BYTE 


.CHCOPY 


9.4.3 .CHCOPY (F/B only) 

The .CHCOPY request opens a channel for input, logically connecting it 
to a file which is currently open by the other job for either input or 
output* This request may be used by either the foreground or the 

background. .CHCOPY must be done before the first .READ or .WRITE. 


Macro Calls 
where s 


.CHCOPY .area, .chan, .ochan 

.chan is the channel which the job will use to read 

the data. 

.ochan is the channel number of the other job which 

is to be copied 


Request Format: 

RO =#• .area: 


13 .chan 


.ochan 


.CHCOPY is legal only on files which are on disk or DECtape; however, 

no errors are detected by the system if another device is used. (To 
close a channel following use of .CHCOPY, use either the .CLOSE or 
.PURGE request.) 


Notes: 

1. If the other job's channel was opened via an .ENTER in order 
to create a file, the copier's channel indicates a file which 
extends to the highest block that the creator of the file had 
written at the time the .CHCOPY was executed. 
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2* A channel which is open on a nonfile-structured device 
should not be copied, because intermixture of buffer requests 
may result. 

3. A program can write to a file (which is being created by the 
other job) on a copied channel just as it could if it were 
the creator. When the copier's channel is closed, however, 
no directory update takes place. 

Errors: 

Code 


0 


1 

Example s 

In this example,.CHCOPY is used to read data currently being written 
by the other job. The correct block number and channel to read is 
obtained by a .RCVDW command. The channel number will be in MSG+4. 


Explanation 

Other job does not exist, does not have 
enough channels defined, or does not have the 
specified channel (.ochan) open. 

Channel (.chan) already open. 



«MCALL 
• » V2 a • 

.. V2..i.REGOEF 



,REG06F 
•MCALL 

.CHCOPY,.RCVDW, 

.PURGE,.READW,.EXIT,.PRINT 

ST 1 

.PURGE 

#0 

( MAKE SURE HE HAVE CLEAR 
(CHANNEL 


.RCVDW 

PARE A,#MSG,#2 

(READ TWO WORDS, BLOCK P 
(AND CHANNEL 


BCS 

NOJOB 

(NO JOB THERE 


.CHCOPY 

PAREA,P0,M8G+P 

(CHANNEL P IS IN THERE 


BCS 

BUSY 

(BUT BUSY 


.READW 

•AREA,f0,P0UPF» 

*25fc,,MSG*2 (GET ThE CORREt 


BCS 

ROERR 



.PRINT 

.EXIT 

POKMSG 


NOJOB I 

.PRINT 

.EXIT 

PMSG1 


BUSY 1 

.PRINT 

.EXIT 

PMSG2 


roerri 

.PRINT 

.exit 

PMSG3 


AREAI 

.BLKW 

5 


MSG > 

.6LKW 

5 


BuFFl 

.BLKW 

2SS. 


MSG 1 1 

.ASCII 

/NO JOB 1/ 


M3G2I 

.ASCIZ 

/BUSY 1 / 


MSG 3 * 

.ASCII 

/READ ERROR/ 


OKMSGt 

.ASCII 

/READ OK/ 


.EVEN 

.EXIT 

.END 

ST 



BLOCK 
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.CLOSE 


9.4.4 .CLOSE 

The .CLOSE request terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated 
device must be in memory. 

Macro Calls .CLOSE .chan 


Request Formats 


RO $ 6 .chan 


A .CLOSE is required on any channel opened for either input or output. 
A .CLOSE request specifying a channel that is not opened is ignored. 

A .CLOSE performed on a file which was opened via .ENTER causes _th® 
device directory to be updated to make that file permanent. A file 
opened via .LOOKUP does not require any directory operations. If the 
device associated with the specified channel already contains a file 
with the same name and extension, the old copy is deleted when the new 
file is made permanent. When an entered file is .CLOSEd, its 
permanent length reflects the highest block written since it was 
entered; for example, if the highest block written is block number 0, 
the file is given a length of 1; if the file was never written, it is 
given a length of 0. If this length is less than the size of the area 
which was allocated at .ENTER time, the unused blocks are reclaimed as 
an empty area on the device. 


Errors: 

.CLOSE does not return any errors. If the device handler for the 
operation is not in memory, a fatal monitor error is generated. 

Examples 

An example which illustrates the .CLOSE request follows the discussion 
of the .WRITW request in Section 9.4.47. 
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9.4.5 .CMKT (F/B only) 

f®<*uest causes ° ne or more outstanding mark time requests to 
e cancelled (mark time requests are discussed in Section 9.4.22). 

Macro Calls .CMKT .area, .id, .time 


where: .id 


is a number used to identify each mark 
request to be cancelled. If more than one 
time request has the same .id, that with 
earliest expiration time is cancelled. If 
0, all nonsystem mark time requests (i.e., xn 
the range 1-177377) for the issuing job are can¬ 
celled. 


time 
mark 
the 
. id = 
in 


• time 


Request Format: 


Notes: 


is the pointer to a two-word area in which the 
Monitor will return the amount of time 
remaining in the cancelled request. The first 
word contains the high-order time, the second 
contains the low-order, if an address of 0 is 
specified, no value is returned, if .id = 0, 
the .time parameter is ignored and need not be 
indicated. 


R0 4 .area: 


23 0 


.id 


.time 


1 . 

2 . 


Cancelling a mark time request 
element for other uses• 


frees the associated queue 


A mark time request can be converted into a timed wait bv 

issuing a .CMKT followed by a .TWAIT, and specifying the same 
.time area. 


Errors: 



Explanation 

*^. was . not zero '* a ">ark time with that 
identification number could not be found (implying 
that the request was never issued or that it has 
already expired). 
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Example: 

See the example following the description of the .MRKT request. 


.CNTXSW 


9.4.6 .CNTXSW (F/B only) 


A context switch is an operation performed when a transition is made 
from rSning one job to running th. other. The .CHTXSW request re 
used to specify locations to be included in the context switch. 


Macro Call: .CNTXSW .area, .addr 


where: .addr 


is a list of addresses terminated by a zero 
word. The addresses in the list must be even 
and: 


a. in the range 2-476, or 

b. in the user job area, or 

c. in the I/O page (addresses 
160000-177776). 


Request Format: 

R0 $ .area: 


33 


.addr 


The system always saves the parameters it needs to uniquely identify 
and execute a job, including all registers, and the locations: 


34/36 Vector for TRAP instruction 

40-52 System Communication Area 


If an .SFPA request (Section 9.4.37) has been executed with a non-zero 
address, all floating point registers and the floating point status 
are also saved. 


It is possible that both jobs may want to share the use of a 
particular location and that location is not included in normal 
context switch operations. For example, if a program uses the IOT 
instruction to perform some internal user function (such as print 
error messages), it must set up the vector at 20 and 22 to point to an 
internal IOT trap handling routine. If both foreground and background 
wish to use IOT, the IOT vector must always point to the proper 
location for the job which is executing. Including locations 20 and 
22 in the .CNTXSW list for both jobs will accomplish this. 


If .CNTXSW is issued more them once, only the latest list is used; 
the previous address list is discarded. Thus, all addresses to be 
switched must be included in one list. If the address (.addr) is 
zero, no extra locations are switched. The list may not be in an area 
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into which the USR swaps, nor may it be modified while a job is 
running. 

Errors: 

Code Explanation 

0 One or more of the above conditions was violated. 

Example: 

In this example, .CNTXSW request is used to specify that locations 20 
and 22 (IOT vector) and certain necessary EAE registers be context 
switched. This allows both jobs to use IOT and the EAE simultaneously 
yet independently. 



.mcall 

i •V2. », , 

REGDEF,.CNTXSW,.PRINT,.EXIT 



..V2.. 


ICALU POR V2 MACROS 



. REGDEF 


IDEFINE REGISTERS 


START t 

MOV 

#LI8T,R0 

I SET R0 TO OUR OWN LIST 


.CNTXSW 

,«8WAPLS 

1 THE LIST OP ADDR3 IS 

1 AT SwAPLS, 



sec 

IS 




.PRINT 

WAODERR 

MDORESS ERROR (SHOULD 

1 OCCUR) 

NOT 


.EXIT 




ISt 

.PRINT 

.EXIT 

CCNTOK 



SMAPLSt 

. WORD 

20 

1 ADDRESSES TO INCLUDE 

IN LIST 


.WORD 

22 



.WORD 

177302 




.WORD 

177304 




.WORD 

177310 




.WORD 

0 



LIST* 

.byte 

0, 33 

^FUNCTION CODE WORD 



.WORD 

0 

ITHE MACRO FILLS THIS 

ONE, 

ADDERS 1 

.ASCII 

/ADDRESSING ERROR/ 


.EVEN 

CNTOKI 

.ASCII 

/CONTEXT 

SWITCH 0.K./ 


.EVEN 

.END 

3TA.RT 




.CSIGEN 


9.4.7 .CSIGEN 

The .CSIGEN request calls the Command String Interpreter (CSI) in 
general mode to process a standard RT-11 command string (see Chapter 2 
for the description of a standard command string). In general mode, 
all file .LOOKUPS and .ENTERS as well as handler .FETCHs are 
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performed. When called in general mode* the CSI closes channels 0—10 
(octal). 


Macro Call: .CSIGEN .devspc, .defext, .cstring 


where: .devspc 

.defext 

.cstring 


is the address of the memory area where the 
device handlers (if any) are to be loaded. 

is the address of a four—word block which 
contains the RAD50 default extensions. These 
extensions are used when a file is specified 
without an extension. 

is the address of the ASCIZ input string or a 
#0 if input is to come from the console 
terminal. (In a F/B environment only, if the 
input is from the console terminal, an 
.UNLOCK of the USR is automatically 
performed, even if the USR is locked at the 
time.) If the string is in memory, it must 
not contain a <CRXLF>, but must terminate 
with a zero byte. If the .cstring field is 
left blank, input is automatically taken from 
the console terminal. 


.CSIGEN loads all necessary handlers and opens the files as specified. 
The area specified for the device handlers must be large enough to 
hold all the necessary handlers simultaneously. If the device 
handlers exceed the area available, the user program may be destroyed. 
The system, however, is protected from this. 

When the EMT is complete, register 0 points to the first available 
location above the handlers. 

The four—word block pointed to by .defext is arranged as: 

Word 1: default extension for all input channels 

Words 2,3,and 4: default extensions for output channels 0,1,2 

respectively 

If there is no default for a particular position, the associated word 
must contain a zero. All extensions are expressed in Radix 50. For 
example, the following block can be used to set up default extensions 
for a macro assembler: 

DEFEXT: .RAD50 "MAC" 

.RAD50 "OBJ" 

.RAD50 "LST" 

.WORD 0 

In the command string: 

*DT0:ALPHA,DTI:BETA=DT2:INPUT 

the default extension for input is MAC; for output, OBJ and LST. The 
following cases are legal: 

* DT 0:OUTPUT= 

*DT2:INPUT 

In other words, the equal sign is not necessary in the event that only 
input files are specified. Q __. 
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When control returns to the user program after a call to .CSIGEN, all 
the specified files have been opened for input and/or output. The 
association is as follows: the three possible output files are 
assigned to channels 0 , 1 , and 2; the six input slots are assigned to 
channels 3 through 10. A null specification causes the associated 
channel to remain inactive. For example, in the following string: 

*,LP:=Fl,F2 

channel 0 is inactive since the first slot is null. Channel 1 is 
associated with the line printer, and channel 2 is inactive. Channel 
3 and 4 are associated with two files on DK:, while channels 5 through 
10 are inactive. The user program can determine whether a channel is 
i°ac5ve SJ Suing » °" “>• “'° oi!,tea channei, which 

returns an error if the channel is not open. 

Switches and their associated values are returned on 

Section 9.4,8.1 for a description of the way switch information 1 
passed. 

Errors: 

If CSI errors occur and input was from the console terminal, an error 
message describing the fault is printed on ^ terminal and the CSI 
retries the command (these messages appear in Section 9.4.8.1). If the 
input was from a string, the carry bit is set and byte 52 contains the 
error code. The errors are* 


Code 

0 

1 

2 

3 


Explanation 

Illegal command (bad separators, illegal filename, 
command too long, etc.)• 

A device specified is not found in the system tables. 
Unused, 

An attempt to .ENTER a file failed because of a full 
directory. 

An input file was not found in a .LOOKUP. 


Example: 

This example uses the general mode of the CSI in a program to copy an 
input file to an output file. Command input to the CSI is from the 

console terminal. 

.MCALL . • V2,. , .RE606F 
.« V2 ,« 

:SKE' ,CSIGEN,,RE ADM,.PRINT,,EXIT,.WRITW,,CLOSE,,8RESET 


ERRWD*52 

STARTl .CSIGEN PDSPACE,#0EXT 


I GET STRING FROM TERMINAL 

MOV R0,BUFF |R0 HAS FIRST FREE LOCATION 

CLR INBLK fINPUT BLOCK • 

MOV #LIST,RS IEMT ARGUMENT LIST 

READ* ,REA0W R5,#3,BUFF,#256.,INBLK |READ CHANNEL 3 
8C C 2S I NO ERRORS 

T8TB MERRwD ERR0R7 

BEO EOF I TES 

MOV AINERR,RB 
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1SI 

.PRINT 



clr 

R0 

ESI 

.EXIT 

.WRITW 

R5,#0,BUFF,$256 


BCC 

NOERR 


MOV 

PWTERR,R0 


BR 

IS 

NOERRl 

INC 

INBLK 


BR 

READ 

EOF 1 

•CLOSE 

#0 


.CLOSE 

#3 


.5RE3ET 

BR 

start 

OEXTl 

.WORD 

0 i 0,0,0 

BUFFI 

.WORD 

0 

INBLKi 

.WORD 

0 

LISTI 

• BLKW 

5 

INERRI 

.A3CIZ 

/INPUT ERROR/ 

WTERRl 

.even 

.asciz 

/OUTPUT ERROR/ 

OSPACE*. 

• EVEN 

.end 

START 


I ERROR MESSAGE 
I HARO EXIT 

,*IN8LK |WRITE THE BLOCK 
INO ERROR WRITING 

I HARO OUTPUT ERROR 
I GET NEXT BLOCK 
I LOOP UNTIL DONE 
I CLOSE OUTPUT CHANNEL 
IANO INPUT CHANNEL 
IRELEASE HANDLER FROM MEMORY 
»GO FOR NEXT COMMAND LINE 

INO default extensions 

#1/0 BUFFER START 
IRELATIVE BLOCK TO READ/WRITE 
IEMT ARGUMENT LIST 


I HANDLER SPACE 


.CSISPC 


9.4.8 .CSISPC 


3^ .CSISPC request calls the Command String Interpreter in special 
mode to parse the command string and return file descriptors and 
switches to the program, m this mode, the cS 2oes not pSfom ant 
handler fetches, .CLOSES, .ENTERS, or .LOOKUPS. ^ 


Macro Calls .CSISPC .outspc, .defext, .cstring 


where t .outspc 


.defext 


xs the address of the 39-word block to 
contain the file descriptors produced by 
.CSISPC. This area may overlay the space 
allocated to .cstring if desired. 


is the address of a four-word block which 
contains the RAD50 default extensions. These 
extensions are used when a file is specified 
without an extension. 
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.cstring is the address of the ASCIZ input string or a 
#0 if input is to come from the console 
terminal. If the string is in memory, it 
must not contain a <CRXLF> but must 
terminate with a zero byte. If .cstring is 
blank, input is automatically taken from the 
console terminal. 

The 39-word file description consists of nine file descriptor blocks 
(five words for each of three possible output files; four words for 
each of six possible input files) which correspond to the nine 
possible files (three output, six input). If any of the nine possible 
filenames are not specified, the corresponding descriptor block is 
filled with zeroes. 

The five-word blocks hold four words of RAD50 representing 
devsfile.ext, and 1 word representing the size specification given in 
the string. (A size specification is a decimal number enclosed in 
square brackets [], following the output file descriptor.) For 
example, 

*DT3:LIST.MAC[15]=PR: 

Using special mode, the CSI returns in the first five word slot: 

16101 .RAD50 for DT3 

46173 .RAD50 for LIS 

76400 .RAD50 for T 

50553 .RAD50 for MAC 

00017 Octal value of size request 

In the fourth slot (starting at an offset of 36 (octal) bytes into 
.outspc), the CSI returns: 

63320 .RAD50 for PR 

0 No file name 

0 Specified 

0 

Since this is an input file, only four words are returned. 

Switches and their associated values are returned on the stack. See 
Section 9.4.8.1. 

Errors: 

Errors are the same as in general mode. However, since .LOOKUPS and 
.ENTERS are not done, the error codes which are valid are: 

Code Explanation 

0 Illegal command line 

1 Illegal device 


Example: 

This example illustrates the use of the special mode of CSI. This 
example could be a program to read a file which is not in RT-11 format 
to a file under RT-11. 
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.MCALL m 111 |RtC0EF 
.. V2.. 

.REGDEF 

.MCALL ,CSISPC,.PRINT,.EXIT,.ENTER,.CLOSE 


STARTl .CIISPC *0UTSPC,P0EXT,#C3TRNG (GET INPUT FROM A 

( STRING IN MEMORY 

2S 

iSYNERR,R0 (SYNTAX ERROR 

(ERROR MESSAGE 


IS! 

231 

331 


see 

MOV 

.PRINT 

.EXIT 

.ENTER 

BCC 

MOV 

6R 

J»R 


.CLOSE 

.EXIT 


*LIST,«0,*OUTSPC,»M. (ENTER FILE UNDER RT-li 

33 

•ENM3G,R0 (ENTER FAILED 

IS 

R5,INPUT (ROUTINE INPUT RILL USE 

(THE INFORMATION AT 
(*0UTSPC*3fe TO READ INPUT 
(FROM THE NON-RTlt DEVICE. 
(INPUT IS PROCESSED AND 
(WRITTEN VIA ,WRITW REQUESTS 
#0 (MAKE OUTPUT FILE PERMANENT 

(AND EXIT PROGRAM 


CSTRNGI 

.ASCII 

"DT<URTFIL.MAC«DT21003,MAC" 

DEXTI 

.EVEN 

.WORD 

0 , 0 , 0 , 0 

(NO 0EFAULT EXTENSIONS 

LISTI 

.BLKW 

5 

(LIST FOR EMT CALLS 

SYNERRI 

, A3CIZ 

"CSI ERROR" 


ENMSGI 

.ASCII 

"ENTER FAILED" 


INPUTl 

.EVEN 

RTS 

R5 


OUTSPC* 

• 


(CSI LIST GOES MERE 


.END 

START 


'.4.8.1 

Passing 

Switch Information 


In both general and special modes of the CSI, switches and their 
associated values are returned on the stack. A CSI switch is a slash 
(/) followed by any character. The CSI does not restrict the switch 
to printing characters, although it is suggested that printing 
characters be used wherever possible. The switch can be followed by 
an optional value, which is indicated by a : or 1 separator. The : 
separator is followed by either an octal number or by one to three 
alphanumeric characters, the first of which must be alphabetic, which 
are converted to Radix-50. The I separator is followed by a decimal 
value. Switches can be associated with files with the CSI. For 
example: 

*DK s FOO/A,DT4 s FILE.OBJ/A s10 0 

In this case, there are two A switches. The first is associated with 
the input file DK:FOO. The second is associated with the input file 
DT4:FILE.OBJ, and has a value of 100(8). The stack output of the CSI 
is as follows: 
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Word # 


Value 


1 N 

(top of 
stack) 


Meaning 


Number of 
command string, 
were found. 


switches 
If N=0, no 


found in 
switches 


Switch value 
and file number 


Switch value 
or next switch 


Even byte - 7-bit ASCII switch value. 

Bits 8-14 = Number (0-10) of the file 
with which the switch is 
associated. 

Bit 15 = 1 if the switch had a 

value. 

“ 0 if the switch had no 

value. 

If word 2 was less than 0, word 3 = 
switch value. if word 2 was 
greater than 0, this word is the 
next switch value (if it exists). 


For example, if the input to the CSI Iss 

*FILE/B:20,FIL2/E=DT3:INPUT/X:SY:20 
on return, the stack is: 

Stack Pointer—» 


505 

100102 

20 


3 

Three switches 

appeared. 


101530 

Last switch=X; 
value. 

with 

file 

3, has a 

20 

Value of switch 

X=20 



101530 

Next switch “X; 
value. 

with 

file 

3 9 has a 

075250 

Next value of switch 

X=RAD50 

code for 


Next switch=E; associated with file 1, 
no value. 

Switch=B; associated with file 0 and 
has a value. 

Value is 20. 


As an extended example, assume the following string was input for the 
cbi in general mode: 


*FILE[8],LP:,SY:FILE2[20]=PR:,DT1:IN1/B,DT2:IN2/M:7 


Assume also that the default extension block is: 


DEFEXT: .RAD50 'MAC' 

.RAD50 'OP1' 

.RAD50 *OP2' 

.RAD50 'OPS' 

The result of this CSI call would be: 


;INPUT EXTENSION 
;FIRST OUTPUT EXTENSION 
;SECOND OUTPUT EXTENSION 
;THIRD OUTPUT EXTENSION 


1 . 


A named FILE.OP1 is entered on channel 0 on 

channel 1 is open for output to the device LP: 
file named FILE2.0P3 is entered on the system 
channel 2. 


device DK; 
a 20-block 
device on 
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2 . 


3. 


Channel 3 is open for input from paper tape; channel 4 is 
open for input from a file INI.MAC on device DTI; channel 5 
is open for input from IN2.MAC on device DT2. 

The stack contains switches and values as follows: 


2 

102515 

7 

2102 


Explanation 

2 switches found in string. 

Second switch is M, associated with 
Channel 5; has a numeric value. 
Numeric value is 7• 

Switch is B, associated with 
Channel 4; has no numeric value. 


If the CSI were called in special mode 
would be the same as for the general 
table would contains 


(Section 9.4.8), the stack 
mode call, and the descriptor 


.OUTSPCs 


15270 

;.RAD50 

'DK' 

23364 

;.RAD50 

•FIL' 

17500 

;.RAD50 

• e' 

60137 

;.RAD50 

'OP1' 

10 

;LENGTH 

OF 8 BLOCKS 

46600 

;.RAD50 

• lp' 

0 

0 

;NO NAME 

OR LENGTH SPECIFIED 

0 

0 

75250 

;.RAD50 

•SY' 

23364 

;.RAD50 

'FIL' 

22100 

;.RAD50 

'E2' 

60141 

;.RAD50 

•OP3' 

24 

;LENGTH 

OF 20 (DECIMAL) 

63320 

0 

;.RAD50 

'PR' 

u 

0 

16077 

;.RAD50 

•DTI' 

35217 

; .RAD50 

'INI' 

0 

; .RAD50 

i • 

50553 

;.RAD50 

'MAC' 

16100 

;.RAD50 

•DT2' 

35220 

;.RAD50 

•IN2' 

0 

J.RAD50 

• i 

50553 

;.RAD50 

'MAC' 


0 


0 (twelve more zero words 

are returned) 


Keyboard error messages which may occur from incorrect use of the CSI 
when input is from the console keyboard includes 


Message 


Meaning 


?ILL CMD? Syntax error. 

?FIL NOT FND? Input file was not found. 
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?DEV FUL? Output file will not fit. 

PILL DEV? Device specified does not exist. 


Notes: 

1. In many cases # the user program does not need to process 
switches in CSI calls. However, the user at the console may 
inadvertently enter switches. In this case, it is wise for 
the program to save the value of the stack pointer before the 
call to the CSI, and restore it after the call. In this way, 
no extraneous values will be left on the stack. 

2. In the F/B System, calls to the CSI which require console 
terminal input will always do an implicit .UNLOCK of the USR. 
This should be kept in mind when using .LOCK calls. 


.CSTAT 


9.4.9 .CSTAT (F/B only) 

This request furnishes the user with information about a channel. It 
is supported only in the F/B environment; no information is returned 
in the Single-Job Monitor. 

Macro Calls .CSTAT .area, .chan, .addr 

where: .addr is the address of a 6-word block which is to 

contain the status 


Request Format: 


27 

• chan 

• addr 


The 6 words passed back to the user are: 

1. Channel status word (see Section 9.4.34) 

2. Starting block number of file (0 if sequential-access device 
or if channel was opened with a nonfile—structured .LOOKUP or 
.ENTER) 

3. Length of file (no information if nonfile-structured device 
or if channel was opened with a nonfile-structured .LOOKUP or 
.ENTER) 

4. Highest block written since file was opened (no information if 
nonfile-structured device) 

5. Unit number of device with which this channel is associated 

6. RAD50 of the device name with which the channel is associated 
(this is a physical device name, unaffected by any user name 
ASSIGNment in effect) 
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The fourth word (highest block) is maintained by the .WRITE requests. 
If data is being written on this channel, the highest relative block 
number is kept in this word. 


Errors: 

Code Explanation 

0 The channel is not open. 

Example: 

In this example, .CSTAT is used to determine the .RAD50 representation 
of the device with which the channel is associated. 



.MCALL 

,.V2.. 

. REGDEF 

,MCALL 

,.V2..,,REGDEF,. 

.PRINT, .EXIT 

CSIGEN,.CSTAT 

STI 

aCSIGEN 

«DEVSOC,«DEFEXT 

/ OPEN FILES 


.CSTAT 

•AREA,#0,PADDR 

/GET THE STATUS 


BCS 

NOCHAN 

/CHANNEL 0 NOT OPEN 


MOV 

PADDR+10,R5 

/POINT TO UNIT • 


MOV 

(R5)*,R0 

/UNIT • TO R0 


ADO 

.RAD50 

(PC)♦,R0 
/ 0/ 

/MAKE IT RAO50 


ADD 

(R5),R0 

/GET DEVICE NAME 


MOV 

.EXIT 

R0,OEVNAM 

/DEVNAM HAS RAO50 DEVICE 

ARE A1 

.BLKW 

5 

ZEMT ARG LIST 

ADDRI 

.BLKW 

b 

/AREA FOR CHANNEL STATUS 

DEVNAMI 

,N0RD 

0 

/STORAGE FOR DEVICE NAME 

DEFEXTI 

, WORD 

0,0,0,0 


NOCHANI 

.PRINT 

.EXIT 

• MSG 


MSG 1 

DEVSDC* 

.ASCIZ 

.EVEN 

'.END 

/NO OUTPUT FILE/ 

ST 


.DELETE 


9.4.10 .DELETE 

The .DELETE request deletes a named file from an indicated device. 
Macro Call: .DELETE .area, .chan, .dblk, .count 
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where: .count is used by magtape/cassette only, (Refer to 

Appendix H for more information concerning 
the magtape and cassette handlers.) 

Request Format: 


RO 4 .area: 


0 .chan 


.dblk 


.count 


Note: 


The channel specified in the .DELETE request must not be in use when 
the request is made, or an error will occur. The file is deleted from 
the device, and an empty (UNUSED) entry of the same size is put in its 
place. A .DELETE issued to a nonfile-structured device is ignored. 
.DELETE requires that the handler to be used be in memory at the time 
the request is made. When the .DELETE is complete, the specified 
channel is left inactive. 


Errors: 

Code Explanation 

Channel is active 

File was not found in the device directory 

Example: 


0 

1 


This example uses the special mode of CSI to delete files. 

."CALL ,.V2,.,.REGDEF 

..V2.. 

•REGDEF 

• HC ALL .IRESET,.CSISPC,.DELETE,.PRINT, .EXIT 


STARTl 


NOFILEI 

OEFEXTl 

LIST* 

0UT3PC* 


.•RESET 

.CSISPC POUTSPC,POEFEXT 
•DELETE #LIST,«0,RINSPC 


BCC 

.print 

BR 

.AiCIZ 
.EVEN 


START 
PNOFILE 
START 
/FILE NOT 


{MAKE SURE CHANNELS 
{ARE FREE 
{GET COMMAND LINE 
{TERMINAL DIALOG WAS 
(OTlFILE 

{USE CHANNEL 0 TO 
(OELETE THE FILE 
{WHICH IS AT THE 
{FIRST INPUT SLOT, 
{OK, LOOP AGAIN 
{NO SUCH FILE 


FOUND/ 


.RAO50 /MAC/ 
.HORD 0,0,0 
.BLKW 2 




(.MAC INPUT EXTENSION 
(NO OUTPUT DEFAULTS 
(EMT ARG LIST 


INSPC-.06 


.BLKW 39. 
,EN0 START 


INSPC is the address of the first input slot in the CSI input table. 
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.DEVICE 


9.4.11 .DEVICE (F/B Only) 

This request allows the user to set up a list of addresses to be 
loaded with specified values when a program is terminated. Upon an 
.EXIT or CTRL C, this list is picked up by the system and the 
appropriate addresses are set up with the corresponding values. This 
function is primarily designed to allow user programs to load device 
registers with necessary values. In particular, it is used to 
off a device's interrupt enable bit when the program servicing the 
device terminates. 

Macro Calls .DEVICE .area, .addr 

where: .addr is the address of the list of masks and 

words. 


Request Format! 


RO 4 


.area: 


14 

0 

.addr 


The list is composed of address/value pairs and should be terminated 
by a 0 address. Only one list can be active at a given time. If 
multiple .DEVICE requests are given, the last list specified is the 
one used. 


Note: 

When the job is terminated for any reason, the list is scanned once. 
At that point, the monitor disables the feature until another .DEVICE 
call is executed. Thus, background programs which are re-enterable 
should include .DEVICE as a part of the reenter code. 


Errors: 


None. 


Example: 

The following example shows how .DEVICE is used to disable interrupts 
from the AFC11 (A-D converter sub-system). 

,MC*LU ,,V2,#t.RE6DEF 
,• V2 , • 

.REGOEF 

.MCM.L .DEVICE,.EXIT 


START! .DEVICE «IX5T 
.EXIT 

LIST! .BYTE 0#14 


IEMT ARG LIST 
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•WORO ATQD 
ATODJ 172570 
0 
0 

.END START 


I ADDRESS IS 172570 

I JAM A 0 INTO IT 

J THIS 0 TERMINATES THE LIST, 


.DSTATUS 


9.4.12 .DSTATUS 

This request is used to obtain information about a particular device. 
Macro Calls .DSTATUS .cblk, .devnam 

where: .cblk is the 4-word space used to store the status 

information. 


.devnam is the pointer to the RAD50 device name. 


•DSTATUS looks for the 
returns four words 
•cblk. The four words 


device specified by .devnam and, if found, 
of status starting at the address specified by 
returned are: 


1. Status Word 

Bits 7-Os contain a number which identifies the device in 

question. The values (octal) currently defined 
ares 

0 = RK05 Disk 

1 = TC11 DECtape 

2 = Reserved 

3 = Line Printer 

4 = Console Terminal 
5,6 = Reserved 

7 = PC11 High-speed Reader 

10 = PC11 High-speed Punch 

11 = Magtape (TM11, TMA11) 

12 = RFll Disk 

13 = TA11 Cassette 

14 = Card Reader (CR11, CM11) 

15 = Reserved 

16 = RJS03/4 Fixed-head Disks 

17 = Reserved 

20 = TJU16 Magtape 

21 = RP02, RP03 Disk 

22 = RX01 Disk 

Bit 15: 1= Random-access device (disk, DECtape) 

0= Sequential-access device (line printer, paper tape, 
card reader, magtape, cassette, terminal) 

Bit 14: 1= Read-only device (card reader, paper tape reader) 

Bit 13: 1= Write-only device (line printer, paper tape punch) 

Bit 12: 1= Non RT-11 directory-structured device (magtape, 

cassette) 
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Bit 11: 1= Enter handler abort entry every time a job is aborted 

0= Handler abort entry taken only if there is an active 
queue element belonging to aborted job 
Bit 10: 1= Handler accepts .SPFUN requests (e.g., MT, CT, DX) 

0= .SPFUN requests are rejected as illegal 


2. Handler size. 

The size of the device handler, in bytes. 

3. Entry point. 

Non-zero implies the handler is now in memory; zero 
implies it must be .FETCHed before it can be used. 

4. Device size. 

I The size of the device (in 256-word blocks) for block- 

replaceable devices; zero for sequential-access devices. 

The device name may be a user— assigned name. 

| Refer to the RT-11 Software Support Manual for greater detail. 

Errors: 

Code Explanation 

0 Device not found in tables. 

Example: 

This example shows how to determine if a particular device handler is 
in memory and, if it is not, how to .FETCH it there. 


.MCALL ..V2•,,•REGOfF 
..V2.. 

.REGDEF 

,MCALL .OSTATUS,.PRINT, .EXIT, .FETCH 


STARTl 


1SI 


2SI 

CORE! 

FPTRI 

FEFAILI 

ILLOEVI 

FECHOKI 

HNDLR*. 


i PCORE,PFPTR 

IS 

PILLOEV 

CORE** 

21 

PHNDLR, PFPTR 

2 $ 

PFEFAIL 

PFECHOK 


(GET STATUS OF DEVICE 
(DEVICE NOT IN TABLES 
(IS DEVICE RESIDENT? 
(NO, GET IT 
(FETCH FAILED 


.END 


4 (DSATUS GOES HERE 

/DT0/ (DEVICE NAHE 

/FILE HAC/ (FILE NAME 
/FETCH FAILED/ 

/ILLEGAL DEVICE/ 

/FETCH 0.K,/ 

(HANDLER WILL GO HERE 

START 
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.ENTER 


9.4.13 .ENTER 

The .ENTER request allocates space on the specified device and creates 

a tentative entry for the named file. The channel number specified is 
associated with the file. (Note that if the program is overlaid, 
channel 15 is used by the overlay handler and should not be modified.) 

Macro Call: .ENTER .area, .chan, .dblk, .length, .count 


where: .length is the file size specification. The file 

length allocation is as follows: 


0 - either 1/2 the largest empty entry or 
the entire second largest empty entry, 

whichever is largest. (A maximum size 
for non-specific .ENTERS may be patched 
in the monitor.) 

M - a file of M blocks. M may exceed the 
maximum mentioned above. 

-1 - the largest empty entry on the device. 


•count file number for magtape/cassette (see 
Appendix H); if this argument is blank, a 
value of zero is assumed. 


Request Formats 


RO .area: 


2 .chan 


.dblk 


.length 

•count 


The file created with an .ENTER is not a permanent file until the 
.CLOSE on that channel is given. Thus, the newly created file is not 
available to .LOOKUP and the channel may not be used by .SAVESTATUS 
requests. However, it is possible to go back and read data which has 
just been written into the file by referencing the appropriate block 
number. When the .CLOSE to the channel is given, any already existing 
permanent file of the same name on the same device is deleted and the 
new file becomes permanent. Although space is allocated to a file 
during the .ENTER operation, the actual length of the file is 
determined when .CLOSE is requested. 


Each job may have up to 256 files open on the system at any time. If 

r !!S Ulred ' a11 256 ma y be opened for output with the .ENTER function. 
.ENTER requires that the device handler be in memory when the request 
is made. Thus, a .FETCH should normally be executed before a .ENTER 
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can be done. On return, RO contains the size of the area actually 
allocated for use. 

Notes: 

When using the 0 length feature of .ENTER, it must be kept in mind 
that less than the largest empty space is allocated. This can have an 
important effect in transferring files between devices (particularly 
DECtape) which have a relatively small capacity. For example, to 
transfer a 200-block file to a DECtape on which the largest available 
empty space is 300 blocks, a 0 length transfer will not work. Since 
the .ENTER allocates half the largest space, only 150 blocks are 
really allocated and an output error will occur during the transfer. 
If a specific length of 200 is requested, however, the transfer will 
proceed without error. 


Explanation 
Channel is in use. 

In a fixed length request, no space greater 
than or equal to M was found, or in a 
non-specific request the device or the 
directory was found to be full. 




0 

1 


Examples 


.ENTER may be used to open a file on a specified device, and then 
write data from memory into that file as follows: 


• HC AIL ..V2..,.FEGDEF,.INTER,.H*XTW,.CLOSE,.PRINT 

• MC ALL .SRESET,.EXIT,.FETCH 
•.V2 t . 

• REGQEF 


START 1 .SRESET 


( MAKE SURE ALL 
1 ARE CLOSED. 

CHANNELS 

.FETCH 

•CORSPC»PFPRT 

(FETCH DEVICE 

HANDLER 

BCS 

BAOFET 

».FETCH ERROR# 

PROBABLY 



.ENTER 

• AREAi#0# RFPRT 

( ILLEGAL 0EVICE. 

fOPEN A FILE ON THE DEVICE 


BCS 

BA0ENT 

( SPECIFIED. LENGTH 0 HILL 

IGIVE 1/2 OF LARGEST EMPTY 
(SPACE NOR available. 

(FAILED. CHANNEL PROBABLY BUSY 


.WRITW 

#AREA,#0,#BUFF, 

*END*BUFF/2# *9 


BCS 

BAOWRT 

(WRITE DATA FROM MEMORY. THE 
I3IZE IS # OF WORDS BETWEEN 
(BUFF AN0 END. START AT BLOCK 
(WRITE FAILURE. 


.CLOSE 

#0 

(CLOSE THE FILE 

FPRTI 

.EXIT 
,RAD50 

/OK / 

(AN0 GO TO KEYBOARD MONITOR. 
(FILE WILL BE ON DK 


.RAD50 

/file ext/ 

(NAMED FILE,EXT 

AREA 1 

,BLKW 

1 El 

(EMT ARGUMENT LIST 

BAOFET 1 

.PRINT 

• FMSG 


January 

1976 


9-48 












Programmed Requests 


BADENTI 

.exit 

.PRINT 

PEMSG 

BADWRTI 

.EXIT 

.PRINT 

PWMSG 

FMSGI 

.EXIT 
, ASCIZ 

/BAD FETCH/ 

EMSGI 

.ASCII 

/BAD ENTER/ 

WMSGI 

. ASCIZ 

/WRITE ERROR/ 

C0R3PCI 

.EVEN 

.BIKW 

400 

BUFF l 


.REPT 

400 


.WORD 

0.1 


.ENOR 


END I 


.END 

START 


ILEAVE 400(e) WORDS 
IFOR OEVICE HANDLER. 

»THIS IS BUFFER TO BE WRITTEN OUT 


.EXIT 


9.4.14 .EXIT 

The .EXIT request causes the user program to terminate. When used 
from a background job under the F/B Monitor and when used under the 
Single-Job Monitor, .EXIT causes KMON to run in the background area. 
All outstanding mark time requests are cancelled. Any I/O requests 
and completion routines pending for that job are allowed to complete. 
If part of the background job resides where KMON and USR are to be 
read, the user job is written onto system device scratch blocks. KMON 
and USR are then loaded and control goes to KMON in the background 
area. If R0=0 when the .EXIT is done, an implicit INIT command is 
executed when KMON is entered, disabling the subsequent use of 
REENTER, START, or CLOSE. 

.EXIT also resets any .GDFN and .QSET calls that were done and 
executes an .UNLOCK if a .LOCK has been done. Thus, the .CLOSE 
command from the Keyboard Monitor does not operate for programs which 
perform .CDFN requests. 

In a F/B system, an .EXIT from a completion routine acts as if a 
double CTRL C has been typed, aborting all I/O in progress before 
exiting. In general, .EXIT from a completion routine should be 
avoided. 

Macro Call: .EXIT 


Errors: 
None. 
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.FETCH 


9.4.15 .FETCH 


The .FETCH request loads device handlers into memory from the system 
device. 

Macro Calls .FETCH .coradd, .devnam 

where: .coradd is the address where the device handler is to 

be loaded. 

.devnam is the pointer to the RAD50 device name. 


The storage address for the device handler is passed on the stack. 
When the .FETCH is complete, RO points to the first available location 
above the handler. If the handler is already in memory, RO keeps the 
same value as was initially pushed onto the stack. If the argument on 
the stack is less than 400 (8), it is assumed that a handler .RELEAS is 
being done. (.RELEAS does not dismiss a handler which was LOADED from 
the KMON; an UNLOAD must be done.) After a .RELEAS, a .FETCH must be 
issued in order to use the device again. 

Several requests require a device handler to be in memory for 
successful operation. These include: 


CLOSE 

LOOKUP 

ENTER 

RENAME 


RE ADC 
WRITC 
READW 
WRITW 


READ 

WRITE 

SPFUN 

DELETE 


Since foreground jobs must have handlers resident, a .FETCH from the 
foreground will give a fatal error if the handler has not been 
previously LOADed. 

Errors: 

Code Explanation 

0 The device name specified does not exist, or 

there is no handler for that device in the 
system. 


Example: 

In the following example, the PR and PP handlers are fetched into 
memory in preparation for their use by a program. The program sets 
aside handler space from its free memory area. 
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,MCALL , .Vi,,, .REGDEF,.FETCH,.PRINT,.EXIT 
.PEGDEF 


START I 

.FETCH FREE r PPRNAME 
BCS FERR 

M 0V R0.R2 

.FETCH R2,«PPNAME 


BCS FERR 

MOV R0.FREE 


IFETCH PR HANDLER 
IFETCH ERROR 

IFETCH PP HANDLER 
I IMMEDIATELY FOLLOWING 
>PR HANDLER, R0 POINTS 
I TO THE TOP OF PR 
»handler ON RETURN 
>FROM THAT CALL, 

INO PP HANDLER 
I UPDATE FREE MEMORV 
> POINTER TO POINT TO 
INEW BOTTOM OF FREE 
I AREA(TOP OF HANDLERS), 



.print 

.exit 

• OK 

OKI 

.ASCII 

.even 

/FETCH O.K, 

FERRI 

.PRINT 

.EXIT 

halt 

• MSG 

PRNAMEI 

•WAO50 

"PR " 

PPNAMEl 

.RAD50 

"PP " 

MSG! 

.ASCII 

.EVEN 

"OEVICE NOT 

FREE! 

.*2 



.end 

start 


JPRINT ERROR MESSAGE 
I AND EXIT 

IOEVICE NAMES 

FOUND" fERROR MESSAGE 

t POINTER TO FREE MEMORY 


.GTIM 

9.4.16 .GTIM 


•GTIM allows user 
time is returned 
past midnight. 


programs to access the current time of day. The 
in two words, and is given in terms of clock ticks 


Macro Call: .GTIM .area, .addr 


where: .addr 


is a pointer to the two words of time 
to be returned. 


Request Format: 

RO .area: 


21 

0 

.addr 
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The high-order time is returned^ the^first -rd, r low-order tig 

in the second word. User? he basic clock frequency (50 or 60 
ticks to hours-minutes-seconds. duration word in the monitor (see 

Hz) may be determined fr °™ .. g the t i me of day is automatically 

Section 9.2.6) . Under a F/BT^i^done^unde-Tthe Single-Job Monitor, 
r it S6 L af noL 24 The "month is not automatically updated under either 
monitor. 

The clock rate is initially set to 60-cycle. Consult the RT-11 Syst em. 
Generation Manual if conversion to a 50-cycle rate is necess y. 

Errors: 


None. 
Example: 



,MCALU 

.•V2 • « 
.REGOEF 

START! 

, ffTIN 

TIME! 

.EXIT 

.WORD 

UI3TI 

,BIKW 


.END 


2 

START 


>L0W AND HI ORDER TIME 
IRETURNEO HERE. 

I ARGUMENTS FOR THE ENT 



9.4.17 .GTJB 

The .GTJB request passes certain job parameters back to the user 
program. 


Macro Call: 
where: 


.GTJB .area, .addr 
. addr 


is the address of an eight-word block into 
which the parameters are passed. The value 
returned ares 

Word 1 - Job Number* (^Background # 

2=Foreground 

2 - High memory limit 

3 - Low memory limit 

4 — Beginning of I/O channel 

space 




__ _ j fnf nro 




Request Format: 

R0 4 .area: 


20 


.addr 
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In the Single-Job Monitor , the job number is always 
limit 0. 2 

In the F/B Monitor 9 the job number can either be 0 oi 

number equals 0 (background job), word 2 equals 0 and wutu * aescnoes 
^ er ® I /° channel words begin. This is normally an address within 
.!* e T^ 1C ^u nt M ° nitor » When a .CDPN is executed, however, the start of 
the I/O channel area changes to the user specified area 9 


0 

and 

the 

low 

2. 

If 

the 

job 


Errors: 
None, 


Example: 


Use .GTJB to determine if this program is executing as a foreground or 
background job. y 


•MCALL ..V2,,,.REGOEF,.GTJB,,PRINT,,EXIT 
.. V2 .. 

,REGDEF 


START I 

.GTJB 

MOV 

TST 

BNE 

MOV 

ISl .PRINT 


•LIST,PJ06ARG 

#FMSG,R1 

JOBARG 

IS 

PBMSG,Rl 
R1 


|R0 POINTS TO 1ST NORD ON 
l RETURN PROM CALU, 

I BACKGROUND? 

INO, PRINT PM8G 


.EXIT 

PMSGI «ASCIZ /PROGRAM IN FOREGROUND/ 

BMSGl .ASCIZ /PROGRAM IN BACKGROUND/ 

.EVEN 


LISTl .BLKM 2 

JOBARGI ,BLKW S, 

.END START 


I ARGUMENTS FOR THE EMT 
1 JOB PARAMETERS PASSED BACK HERE, 


.HERR/SERR 


9.4.18 .HERR/.SERR 

.HERR and .SERR are complementary requests used to govern monitor 
behavior for serious error conditions. During program execution, 
certain error conditions may arise which cause the executing program 
t0 , b e aborted < for example, trying to pass I/O to a device which has 
no handler in memory, or trying to load a device handler over the 
USR). Normally, these errors cause program termination with one of the 
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?M— error messages. However, in certain cases it is not feasible to 
abort the program because of these errors; for example, a multi-user 
program must be able to retain control and merely abort the user who 
has generated the error. .SERR accomplishes this by inhibiting the 
monitor from aborting the job. Instead , it causes an error return to 
the offending EMT to be taken. On return from that request, the C bit 
is set and byte 52 contains a negative value indicating the error 
condition which occurred. 

.HERR turns off user error interception and allows the system to abort 
the job on fatal errors and generate an error message. (.HERR is the 
default case.) 

Macro Calls: .HERR 

.SERR 


Errors: 

Following is a list of the errors which are returned if soft error 
recovery is in effect: 

Code Explanation 

-1 Called USR from completion routine. 

-2 No device handler; this operation needs one. 

-3 Error doing directory I/O. 

-4 FETCH error. Either an I/O error 

occurred while reading the handler, or tried to 
load it over USR or RMON. 

-5 Error reading an overlay. 

-6 No more room for files in the directory. 

-7 Illegal address (F/B only); tried to perform a 

monitor operation outside the job partition. 

-10 Illegal cnannel number; number is greater 

than actual number of channels which exist. 

-11 Illegal EMT; am illegal function code has 

been decoded. 

Traps to 4 and 10, and floating point exception traps are not 
inhibited. These errors have their own recovery mechanism. (See 
Section 9.4.42.) 


Example: 

This example causes a normally fatal error to generate errors back to 
the user program. The error returned is used to print an appropriate 
message. 


.HCALL 

..V2.., •REGDEF * 

.FETCH,.ENTER,.HERR, .SERR 

•ncALL 
• •V2 • « 

, REGDEF 

.EXIT,.PRINT 


, SERR 


; TURN ON SOFTWARE ERROR 
(RETURNS 

.RETCH 

•holr,#ptr 

IGET A DEVICE HANDLER 

BCS 

RCHERR 

1 OPEN A FILE ON CHANNEL 1 

.ENTER 

RAREA,#1,»PTR 

BCS 

ENERR 
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.HERR 

.EXIT 


MOW PERMIT TM.ERRORS, 

FCHERRl 

MOVB 

PP52.R0 

MAS IT FATAL 


BMI 

FTLERR 

> YES 


.PRINT 

.EXIT 

PFMS6 

MO... NO DEVICE BY THAT NAME 

ENERRl 

Move 

PP52.R0 



BMI 

FTUERR 



.PRINT 

.EXIT 

FEMSG 


FTLERRI 

NES 

R0 

1 TH13 WILL TURN POSITIVE 


OEC 

R0 

1 ADJUST BY ONE 


ASl 

R0 

MAKE IT AN INDEX 


MOV 

TBL(R0)»R0 

1 PUT MESSAGE ADDRESS INTO R0 


.PRINT 
• EXIT 


1 AND PRINT IT, 

T8L 1 

Ml 


fCAN'T OCCUR IN THIS PROGRAM 


M2 


MO DEVICE HANDLER IN MEMORY 


M3 

* 

1 DIRECTORY I/O ERROR 


M« 


IFETCH ERROR 


M5 


IMPOSSIBLE FOR THIS PROGRAM 


MB 


INO ROOM IN DIRECTORY 


M7 


IILLEGAL ADDRESS (F/B) 


M i 0 


1 ILLEGAL CHANNEL 


Mil 


IILLEGAL EMT 

HU 



ICAN'T OCCUR IN THIS PROGRAM 

M21 

.A8CIZ 

/NO DEVICE HANDLER/ 

M] t 

• A SC X Z 

"DIRECTORY I/O 

ERROR" 

M«l 

. ASCIZ 

/ERROR DOING FETCH/ 

M5I 



MOT APPLICABLE TO THIS PROGRAM 

Mfcf 

.ASCIZ 

/NO ROOM IN DIRECTORY/ 

M7I 

.ASCIZ 

/ADDRESS CHECK 

ERROR/ 

HI 01 

.ASCIZ 

/ILLEGAL CHANNEL/ 

Mill 

.ASCIZ 

/illegal emt/ 


FHS6I 

.ASCIZ 

/FETCH FAILED/ 


EHS6I 

.ASCIZ 

.EVEN 

/ENTER FAILED/ 


HOIRI 

,BLKW 

300 

1 LEAVE 300 (OCTAL) FOR HANDLER 

PTRI 

, RAO50 

/DT4/ 

IDEVICE AND FILE NAME, 


.RAO50 

/exahpl/ 



.RAD50 

/MAC/ 


ARE A1 

. 6LK H 

4 

1EMT AREA 


.END 

ST 



.HRESET 


9.4.19 .HRESET 

This request performs the same function as .SRESET, after stopping all 
I/O transfers in progress for that job. (.HRESET is not used to clear 
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a hard-error condition.) Note that in the single-job environment, a 
hardware RESET instruction is used to terminate I/O, while in a F/B 
environment, only the I/O associated with the job which issued the 
.HRESET is affected. All other transfers continue. 

Macro call: .HRESET 

Errors: 

None. 

Example: 

See the example for .SRESET (Section 9.4.40) for format. 


.LOCK/.UNLOCK 


9.4.20 .LOCK/.UNLOCK 


.LOCK 

The .LOCK request is used to "lock" the USR in memory for a series of 
operations. If all the conditions which cause swapping are satisfied, 
the user program is written into scratch blocks and the USR is loaded. 
Otherwise, the USR which is in memory is used, and no swapping occurs. 
The USR is not released until an .UNLOCK request is given. (Note that 
in a F/B System, calling the CSI may also perform an implicit 
.UNLOCK.) A program which has many USR requests to make can *LOCK the 
USR in memory, make all the requests, and then .UNLOCK the USR; no 
time is spent doing unnecessary swapping. 

In a F/B environment, a .LOCK inhibits the other job from using the 
USR. Thus, the USR should be locked only as long as necessary. 

Macro Call: •LOCK 

Note that the .LOCK request reduces time spent in file handling by 
eliminating the swapping of the USR in and out of memory. If the USR 
is currently resident, .LOCK is ignored. After a .LOCK has been 
executed, an .UNLOCK request must be executed to release the USR from 
memory. The .LOCK/.UNLOCK requests are complimentary and must be 
matched. That is, if three .LOCK requests are issued, at least three 
• UNLOCKS must be done, otherwise the USR will not be released. More 
.UNLOCKS than .LOCKS may occur without error. 

Notes: 

1. It is vital that the .LOCK call not come from within the area 
into which the USR will be swapped. If this should occur, 
the return from the USR request would not be to the user 
program, but to the USR itself, since the LOCK function 
inhibits the user program from being re-read. 
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2. Once a .LOCK has been performed, it is not advisable for the 
program to destroy the area the USR is in, even though no 
further use of the USR is required. This causes 
unpredictable results when an .UNLOCK is done. 

3. If a foreground job performs a .LOCK request while the 
background job owns the USR, foreground execution is 
suspended until the USR is available. Thus, in this case, it 
is possible for the background to lock out the foreground (see 
the .TWAIT request). 

Errors: 

None. 

Example: 

See the example following .UNLOCK. 

.UNLOCK 


The .UNLOCK request releases the User Service Routine from 
it was placed there with a .LOCK request. If the .LOCK 
swap, the .UNLOCK loads the user program back into memory, 
does not require swapping, the .UNLOCK acts as a no-op. 


memory if 
required a 
If the USR 


Macro Calls .UNLOCK 
Notes: 

1. It is important that at least as many .UNLOCKS are given as 
.LOCKS. If more .LOCK requests were done, the USR remains 
locked in memory. It is not harmful to give more UNLOCKS 
than are required; those that are extra are ignored. 

2. The .LOCK/.UNLOCK pairs should be used only when absolutely 
necessary when running two jobs in the F/B system. When a 
job .LOCKs the USR, the other job cannot get at it until it 
is .UNLOCKed. Thus, the USR should not be .LOCKed 
unnecessarily, as this may degrade performance in some cases. 

3. In a F/B System, calling the CSI with input coming from the 
console terminal performs an implicit .UNLOCK. 


Errors: 


None. 


Example: 


This example shows the usage of .LOCK, .UNLOCK, and their interaction 
with the system. 


.MCALL 
.MCALL 
.. V2 .. 

•REGDEF 


..V2,,,,REGDEF,.LOCK,.UNLOCK,.LOOKUP 
.SETTOP,.PRINT,.EXIT 


START I 


3YSPTR»54 


.SETTOP PP8YSPTR |TRY FOR ALL OF MEMORY 

M 0V R0,TOP ;R0 HAS THE TOP 
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• U 0 L n 


.LOOKUP PLIST,P0, PFILEl 



BCC 

IS 

2S( 

.PRINT 

.EXIT 

• LM8G 

i s> 

MOV 

•LIST,R0 


INC 

(R0) 


MOV 

•FILES,2(R0) 


.LOOKUP 

(ALL Al 


BC8 

.UNLOCK 

.EXIT 

2S 

LISTI 

,BLKW 

3 

FILEH 

,RAO50 

/DK / 


.RADS0 

/FILE! MAC/ 

FILE2I 

,RAD50 

/OK / 


.RAD50 

/FILE2 MAC/ 

TOPI 

.WORD 

0 

LM3G ( 

. A8CIZ 
.EVEN 

/LOOKUP ERROR/ 


.END 

START 


|BRING U8R INTO MEMORY 
(LOOKUP A PILE ON CHANNEL 0 
(ON ERROR, PRINT A 
(MESSAGE AND EXIT 


(DO LOOKUP ON CHANNEL 1 
(NEW POINTER 
iS ARE FILLED IN 


(NOW RELEASE usr 


(SPACE FOR ARGUMENTS 


In the above example, .SETTOP tries to obtain as much memory as it 
can. Most likely this will, in a background job, make the USR 
non-resident (i.e., unless a SET USR NOSWAP command is done at the 
keyboard). Thus, if the USR were non-resident, swapping must take 
place for each .LOOKUP given. Using the .LOCK, the USR is brought 
into memory and remains there until the .UNLOCK is given. 

The second .LOOKUP makes use of the fact that the arguments have 
already been set up at LIST. Thus, it is possible to increment the 
channel number, put in a new file pointer and then give a simple 
.LOOKUP, which does not cause any arguments to be moved into LIST. 


.LOOKUP 


9.4.21 .LOOKUP 

The .LOOKUP request associates a 
and/or file, for the purpose 
channel used is then "busy" until 
executed: 


specified channel with a device 
of performing I/O operations. The 
one of the following requests is 


.CLOSE 
.SAVESTATUS 
.SRESET 
.HRESET 

.PURGE _ ^ ,. 

.CSIGEN (if channel is in range 0-10 octal) 

Note that if the program is overlaid, channel 15 is used by the 

overlay handler and should not be modified. 
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Macro Call: .LOOKUP .area, .chan, .dblk, .count 

where: .count is an argument which can optionally be used 

for the cassette and magtape handlers. Refer 
to Appendix H for details of this parameter. 
If .count is blank, a value of zero is 
assumed. 


Request Format: 

RO =» 


.area: 


11.chan 

.dblk 

.count 


If the first word of the file name in .dblk is zero and the device is 
a file-structured device, absolute block 0 of the device is designated 
as the beginning of the "file". This technique allows I/O to any 
physical block on the device. If a file name is specified for a 
device which is not file-structured (i.e. PR:FILE.EXT), the name is 
ignored. 

The handler for the selected device must be in memory for a .LOOKUP. 

On return from the .LOOKUP, RO contains the length (number of blocks) 
of the file just looked up. If the length returned is 0, a nonfile- 
structured .LOOKUP was done to the device. 


Errors: 

Code Explanation 

0 Channel already open. 

1 File indicated was not found on the device. 

Example: 


In the following example, the file "DATA.001" on device DT3 is opened 
for input on channel 7. 


.HCALL ,.V2..,.RCGDEP,.PITCH,.LOOKUP,.PRINT,.EXIT 
.. ^2 .• 

.REGDEF 


START! 

ERRH0i52 

.PITCH 

BCS 

.LOOKUP 

see 

T8TB 

BNE 

.PRINT 

.EXIT 

NPOI .PRINT 

.EXIT 

CAMSGl .ASCII 


PH8PACE,PDT3N 
PERR 

•LIST,#7,PDTSN 

LDONE 

PiERRWD 

NPO 

PCAHSG 


I GET DEVICE HANDLER 
1073 IS NOT AVAILABLE 
I LOOKUP THE PILE 
fON CHANNEL T 
IPILE HAS POUND 
)ERROR, WHAT'S WRONG? 
IPILE NOT POUND 
IPRINT 'CHANNEL ACTIVE' 


PNPMSG 


IPILE NOT POUND 


/CHANNEL ACTIVE/ 
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NFM8GI 

.ASCII 

/PILE 

NOT F0UN0/ )ERROR MESSAGES 

DTMSGl 

• ASCIZ 

/DT3 NOT AVAILABLE/ 


.EVEN 



FERRl 

.PRINT 

.EXIT 

4DTMSG 


LOONEl 

.EXIT 


(PROGRAM CAN NOW 
(ISSUE READS AND 
(WRITES TO FILE 
(OATA.001 VIA 
(CHANNEL 7 

LIST! 

.BLKW 

5 


DT3NI 

.RAO50 

"0T3" 

(DEVICE 


.RAQ50 

"DAT" 

(FILENAME 


.RAQ90 

"A « 

(FILENAME 


.RAD50 

''001" 

(EXTENSION 

HSPACEl 



(RESERVED SPACE FOR DT 


,i.*400 


(HANDLER 


.END 

START 



.MRKT 


9.4.22 .MRKT 


The .MRKT request schedules a completion routine to be entered after a 
specified time interval (clock ticks past midnight) has elapsed. 


Macro Call: 


.MRKT .area, .time, .crtn, .id 


where: .time 

.id 


Request Format: 


is the pointer to the two words containing 
the time interval (high-order first; 
low-order second). 

is a number assigned by the user to identify 
the particular request to the completion 
routine and to any cancel mark time requests. 

The number must not be within the range of 
codes from 177400-177777; these are reserved 
for system use. The number need not be 
unique (i.e., several .MRKT requests may 
specify the same .id.) On entry to the 
completion routine, the .id number is in R0. 


R0 4 


.area: 
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.J®KT requests require a queue element taken from the same list as the 
? ueue ®l® ra ® n ts. The element is in use until either the rnmniAfinn 
I ^entered or a cancel mark timerequest IsilsvtT. ?he ^^ 
^locate enough queue elements to handle at least as many mark 
time requests as he expects to have pending simultaneously. 

Errors s 


Code 

0 

Example: 


Explanation 

No queue element was available. 


In this example, a mark time is set up to time out an I/O transfer 

Printed ® x P ir ®® before the transfer is done, a message is 

printed, if the I/O transfer completes before the mark time, the mark 

already S Qpen?^ lle ^* (N ° t6 that *** exaraple assumes the I/O channel is 


.MCALL 

.mcall 

•,V2,, 

•REGDEF 


..V2,.,,REG0EF,,READ,.WAIT,.MRKT 
,QSET,.PRINT,.EXIT,.LOOKUP 


,,CMKT 


ST* 


.LOOKUP 

BCS 

MOV 

, OSET 

.MRKT 

BCS 

.READ 

BCS 

.WAIT 

,CMKT 

BCS 


•AREA, 
LKERR 
•AREA, 
•OUEUE 
(SP), • 
NOMRKT 
•RDLST 
RDERR 
• 0 

(SP),» 

NOTDUN 


•0,*FILE (OPEN A FILE 

(FILE NOT FOUND 
•(SP) (EMT LIST TO STACK 

»*5 I ALLOCATE 3 MORE ELEMENTS 

INTRVL, PMRTN, il MET TIMER GOING 
(FAILED, 

MTART I/O TRANSFER 


1 


I AND WAIT A WHILE, 

MEE IF MARK TIME IS 

(done, 

IFAILED, THAT MEANS THAT 
( THE MARK TIME ALREADY 

(expired. 


.exit 


MRTNI ,CMKT 

.print 

RTS 

LKERRI .PRINT 
.EXIT 

ROERRl .PRINT 
.EXIT 

NOTOUNI .PRINT 
.EXIT 

NOMRKTI .PRINT 
.CXI T 

NOOl .ASCIZ 

faili .asciz 

LMI .ASCIZ 

RDMSGl .ASCIZ 
.even 
INTRVLI .WORD 


( 8p )*Rl (OK, KILL THE TIMER. 

•FAIL ( DON'T WORRY ABOUT AN 

I ERROR HERE, 

PC 

• LM 

•RDMSG 

• FAIL 

• N00 

/NO OUEUE ELEMENTS AVAILABLE/ 

/MARK TIME COMPLETED BEFORE TRANSFER/ 
/LOOKUP ERROR/ 

/READ ERROR/ 

(ALLOW 13 CLOCK 
(TICKS FOR TRANSFER. 
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QUEUE• 

,BLKW 

5*7 

AREA 1 

.BLKW 

5 

FILEI 

.RAO50 

/DK FILE 

ROLSTl 

.BYTE 

0 


.BYTE 

10 

BLOCK! 

.WORD 

0 

.WORD 

BUFF 


.WORD 

256, 


.WORD 

1 

BUFFI 

.BLKW 

256, 


• AREA FOR QUEUE ELEMENTS 
I A FEW WORDS FOR EMT LIST 

•CHANNEL 0 
I A READ 
fBLOCK * 

» buffer 

H BLOCK 


,fND ST 


.MWAIT 


9.4.23 .MWAIT 

This request is similar to the .WAIT request. .MWAIT, however, 
suspends execution until all messages sent by theotherjobhavebeen 
transmitted or received. It provides a means for ensuring that a 
required message has been processed. It should be u ? ed P***" ari *£ 
conjunction with the .RCVD or .SDAT modes of message handling, where 
no action is taken when a message is completed. 


Macro Call: .MWAIT 


Errors: 


None. 


Example: 

This program requests a message, does some intermediate processing, 
and then waits until the message is actually sent. 

.MCALL ..V2..,.REG0EF,,MWAIT,.RCVD,.EXIT,.PRINT 
..VS.. 

.REGOEF 


W0R0S*255, 
START I 

.RCVD 


#AREA,#RBUFF,#W0R0S »GET MESSAGE, 

•INTERMEDIATE PROCESS 


MOV 

,MWAIT 

#RBUFF*2,R5 

CMPB 

(R5)♦,#' A 

BNE 

BADMSG 

.EXIT 

BADMSGI .PRINT 
.EXIT 

PMSG 


•MAKE SURE WE HAVE IT. 
•FIRST CHARACTER AN A? 
•NO, INVALID MESSAGE 
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MSGl 
AREA I 
R8UFFI 


.ASCI2 /bad MESSAGE/ 
tSLKW 10 
,BLKW 256, 

.EVEN 

.END start 



9.4.24 .PRINT 

The .PRINT request causes output to be nrinfo^ = 4 - j-u 

terminal. When a forearounfl ,• „ . P rinted a t the console 

in the job producing output a B> or runnin 9 and a cha nge occurs 

the message has been printed bv ?L• v 1 *?®*"* text following 

background) until another B> or F^is printed^TlS (f ? re ^ r ° und or 

printed may be terminated with either fnulfim^K string to be 

If the null (ASCIZ) format is th. U 4 . ( °i b Y te ° r a 200 b ^ te - 

followed by a <CR><LF>. If a 200 °V tpat 1S automatically 

<CR><LF> is generated. byte terminate s the string, no 

Macro Calls .PRINT .addr 


where: .addr 


is the address of the string to be printed. 


pXS 1 irsr^p« h bu«s. pro9r “” after au h .v. 

s« £o sr°«a,i° b oi[ M ^ a bS?iu„a”^ iat ?; y usin9 - print ■» »tt« 

.PRINT should bs usad (rather than .miS'or!'Soo?| r .“ r,e " t ness ages. 
Errors: 


None. 


Example: 


STARTl 


.NCALU .«V2•.,,REGDEF,.PRINT,.EXIT 
• • v *• • 

.REGDEF 


.print 

.PRINT 


iS2 

*31 


.EXIT 


ill 
321 


.ASCII 

.ASCII 

.BYTE 

.EVEN 


/THIS WILL HAVE CR-LF FOLLOWING/ 
/THIS WILL NOT HAVE CR-LF/ 

200 


.END 


START 
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9.4.25 .PROTECT 

The .PROTECT request is usedhyajob 

SSSJ’S.Let r t^^ 

3*2. 23 .SSSS'inS th^protected Nitons La he g i„ usinq the 

associated device. 


Macro Call: 

where: 


.PROTECT 

.addr 


.area, .addr 

is the address of the word pair to be 
protected. .addr must be ® multiple of 
four, and must be less than 476 (octal). 
The two words at .addr and .addr+2 will be 
protected. 


Request Format: 

RO 4 .area: 


31 

0 

.addr 


Errors: 

Code 

0 
1 

Example: 

This example shows the use of .PROTECT to gain control of the UDCll 
vectors• 


Explanation 

Protect failure; locations already in use. 
Address greater than 476 or not a multiple of 4. 



,NCALL 
..VI.. 
.RE60EF 

STI 

NOV 

NOV 

.RROTECT 

BCS 

NOV 

NOV 


.EXIT 

ERRI 

.RRINT 

.EXIT 

AREA 1 

.SLKW 

NOVECI 

, ASCIZ 


•AREA,-CSP) 
•ISA,AS 
(8R},R5 
ERR 

•UDCINT,(R5)♦ 
#140,(R5) 


•NOVEC 


IU0C VECTOR ADDRESS 
IRROTECT ISA,ISA 
I YOU CAN'T 

UNITIALIZE THE VECTORS, 
I AT LEVEL T 
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.EVEN 

UDCINTI 


.PURGE 


9.4.26 .PURGE 

The .PURGE request is used to de-activate a channel without performing 
a .HRESET, .SRESET, .SAVESTATUS, or .CLOSE request. It merely frees a 
channel without taking any other action. If a tentative file has been 
.ENTERed on the channel, it will be discarded. Purging an inactive 
channel acts as a no-op. 

Macro Call: .PURGE .chan 

Errors: 

None. 

Example: 

The following code is used to make certain that channels 0-7 are free: 

.MCALU ,.V2,. # .REGDEP,.PURGE i .EXIT 
•. V 2.. 

•REGDEF 


START! 

CLR 

R1 

;START WITH CHANNEL 0 

111 

.PURGE 

R1 

1 PURGE A CHANNEL 


INC 

R1 

1 BUMP TO NEXT CHANNEL 


CMP 


IIS IT AT CHANNEL 8 VET? 


BLO 

IS 

1 NO» KEEP GOING 


.EXIT 

.end 

START 



.QSET 


9.4.27 .QSET 

All RT-11 I/O transfers are done through a centralized queue 
management system. If I/O traffic is very heavy and not enough queue 
elements are available, the program issuing the I/O requests may be 
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suspended until a queue element becomes available. In a F/B system, 
the other job runs while the first program waits for the element. 

The .QSET request is used to make the RT-11 I/O queue larger (i.e., 
add available entries to the queue). A general rule to follow is that 
each program should contain one more queue element than the total 
number of I/O requests which will be active simultaneously. Timing 
requests such as .TWAIT and .MRKT also cause elements to be used and 
must be considered when allocating queue elements for a program. Note 
that if synchronous I/O is done (i.e. .READW/.WRITW, etc.) and no 
timing requests are done, no additional queue elements need be 
allocated. 


Macro Calls .QSET .addr, .qleng 

where: .addr is the address at which the new elements are 

to start. 

.qleng is the number of entries to be added. Each 

queue entry is seven words long; hence the 
space set aside for the queue should be 
.qleng * 7 words. 

Each time .QSET is called, a contiguous area of memory is divided into 
seven-word segments and is added to the queue for that job. .QSET may 
be called as many times as required. The queue set up by multiple 
.QSET requests is a linked list. Thus, .QSET need not be called with 
strictly contiguous arguments. The space used for the new elements is 
allocated from the user's program space. Thus, care must be taken so 
that the program in no way alters the elements once they are set up. 
The .SRESET and .HRESET requests discard all user-defined queue 
elements; therefore any .QSETs must be reissued. 

Care should also be taken to allocate enough memory for the queue. 
The elements in the queue are altered by the monitor; if enough space 
is not allocated, destructive references will occur in an unexpected 
area of memory. 

Errors s 

None. 


Example: 

.mcall 

«• Ye . . 

• REGDEF 

. . V 2 . . , 

.RERDFF,.OSFT,.EXIT 




STARTl 

.QSET 

#Q1,*5 

(ADD 5 ELEMENTS TO 
STARTING AT Ql 

THE 

QUEUE 



.QSET 

#Q3,#3 

;AN0 3 MORE AT Q3. 





.EXIT 






Q11 

.BLKW 

7*5. 

IPIR5T QUEUE AREA 

(35 

DECIMAL 

WORDS) 

Q3I 

.BIKW 

7*3, 

;SECOND QUEUE AREA 

(21 

decimal 

WORDS) 


.END 

START 





Note that Ql 

and Q3 

need not 

have been contiguous. 





9-66 



Programmed Requests 


RCTRLO 


9.4.28 .RCTRLO 

The .RCTRLO request ensures that the console terminal is able to 
print. Since CTRL O (tO) struck while output is directed to the 
console terminal inhibits the output from printing until either 
another to is struck or until the program resets the *0 switch, a 
program that has a message which must appear at the console can 
override to struck at the keyboard. 

Macro Call: .RCTRLO 


Errors: 


None 


Example: 


In this example, the user program first calls the CSI in general mode, 
then processes the command. When finished, it returns to the CSI for 
another command line. To make certain that the prompting typed by 
the CSI is not inhibited by a CTRL 0 in effect from the last 
operation, terminal output is re-enabled via a .RCTRLO command prior 
to the CSI call. 


.MCALL .•V2.. 
.. Vi ,, 

• REGDEF 


,.REGDEF,.RCTRLO,.CSIGEN,.EXIT 


START I .RCTRLO 


/MAKE SURE TT OUTPUT IS 
I ENABLED 


CSIGEN 


•DIPACE,#OEXT,#0 /CALL CSI-IT WILL TYPE 


/PROCESS COMMAND 


JMP 


START 


/GET NEXT COMMAND 


OEXTf 0 


INO DEFAULT EXTENSIONS 


0 

0 

0 


DSPACEI ,•,♦400 


/HANDLER SPACE 


.END START 
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.RCVD/.RCVDC/.RCVDW 


9.4.29 .RCVD/.RCVDC/.RCVDW (F/B Only) 

There are three forms of the receive data request; these are used in 
conjunction with the .SDAT (Send Data) requests to allow a general 
data/message transfer system. .RCVD requests can be thought of as 
.READ requests, where data transfer is not from a peripheral device 

but from the other job in the system. Additional queue elements should 
be allocated for buffered I/O operations in .RCVD and .RCVDC requests 
(see .QSET). 

.RCVD 


This request is used to receive data and continue execution. The 
request is posted and the issuing job continues execution. At some 
point when the job needs to have the transmitted message, an .MWAIT 
should be executed. This causes the job to be suspended until the 
message has been received. 


Macro Call: 

• RCVD 

.area, .buff, .went 


where: 

• buff 

is the address of the 

buffer to which the 



message is to be sent. 



•went 

is the number of words 

to be transferred. 


Request Format! 


RO 4 .areas 


26 


(unused) 

.buff 


.went 

I- 


Word 0 (the first word) of the message buffer will contain the number 
of words transmitted whenever the .RCVD is complete. Thus, the space 
allocated for the message should always be at least one word larger 
than the actual message size expected. 


The word count is a variable number, and as such, the .SDAT/.RCVD 
combination can be used to transmit a few words or entire buffers. 
The .RCVD operation is only complete when a .SDAT is issued from the 
other job. 

Programs using .RCVD/.SDAT must be carefully designed to either always 
transmit/receive data in a fixed format or have the capability of 
handling variable formats. The messages are all processed in FIFO 
(first in-first out) order. Thus, the receiver must be certain it is 
receiving the message it actually wants. 
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Errors: 

Code 
0 

Example: 

An example follows the .RCVDW section. 


Explanation 

No other job exists in the system. 


.RCVDC 

The .RCVDC request receives data and enters a completion routine when 
5*)® message is received. The .RCVDC request is posted and program 
execution stays with the issuing job. when the other job sends a 
message, the completion routine specified will be entered. 


Macro Call: .RCVDC 

.area, .buff, .went, .ertn 


where: .buff 

is the address of the buffer to which the 
message is to be sent. 

.went 

is the number of words to 

be transmitted. 

• ertn 

is the completion routine 
Section 9.2.8). 

to be entered (see 


As in the others, word 0 of the buffer contains the number of words 
transmitted when the transfer is complete. 

Request Format: 

RO area: 


26 


(unused) 

.buff 


.went 


.ertn 


Errors: 

Code 
0 

Example: 

An example follows the .RCVDW section. 


Explanation 

No other job exists in the system. 


.RCVDW 

iSdth/Jni! 8 ?? re °® ive data “ d wait * A message request is posted 
and the 30 b issuing the request is suspended until the other iob sends 
a message to the issuing j°b. When the issuing job runs agi?n, Se 
message has been received, and word 0 of the buffer indicates the 
number of words which were transmitted. 
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Macro Call: .RCVDW .area, .buff, .went 
where: .buff 


is the address of the buffer to which the 
message is to be sent. 


.went 

Request Format: 

RO 4 .area: 


is the number of words to be transmitted. 


m 


(unused) 

.buff 


.went 


Errors: 


Code 


Explanation 

No other job exists in the system. 


Example: 

in this example, the running job receives a message from the second 
job and interprets it as the device and filename of a file to be 
opened and used. In this case, the message was " 0 ' JjJ 

the receiving program did not use the transmitted length y 

purpose. 

..V«,,,,REG0EF,.RCV0W,,PURGE,.LOOKUP,,EXIT,,PRINT 


>R5>EMT ANG, AREA 

|heuuest message anu rait 

IAN ERROR? 

ICLEAR CHANNEL 0 
I LOOKUP INQXCATEO PILE 
|ERROR 



.MCALL 

..V2« «,.REGDEF,. 


,R£G0EF 


STARTI 

HOV 

#AREA,R5 


.RCVDW 

R5,iFILE,#« 


ecs 

HERR 


.PURGE 

#0 


•LOOKUP 

R5,#0,#FILE*2 


SCO 

LKERR 


.EXIT 


AREA: 

.8LKW 

10 

FILE: 

,BLKW 

1 


,BLKN 

4 

HERR: 

.PRINT 

#MHSG 

LKERRl 

.EXIT 

.PRINT 

.EXIT 

iLKHSG 

MMSG: 

.A8CIZ 

/MESSAGE ERROR/ 

LKHSGI 

, ASCII 
.EVEN 

/LOOKUP ERROR/ 


.END 

START 


ILEAVE SPACE FOR SAFETY 
FACTUAL wQRD COUNT IS HERE 
|UEVIFILE *EXT ARE HERE 


The issuing job is suspended until the indicated data is transmitted. 
Either of the other modes could have also been used to receive the 

message. 
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.READ/READC/READW 

9.4.30 .READ/.READC/.READW 


RT-11 provides three modes of I/O: .READ/.WRITE, .READC/.WRITC 
.READW/.WRITW. Section 9.4.47 explains the output operations 
input operations are described next. 


and 

The 


Note that in the case of .READ and .READC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET) 


.READ 


The .READ request transfers a specified number of 
specified channel to memory. Control returns to 
immediately after the .READ is initiated. No special 
when the transfer is completed. 


words from the 
the user program 
action is taken 


Macro Call: .READ .area, .chan, .buff, .went, .blk 


where: .buff 


is the address of the buffer to receive the 
data read. 


.went is the number of words to be read. 


• blk is the block number to be read relative to 

the start of the file, not block 0 of the 
device. The monitor translates the block 
supplied into an absolute device block 
number. The user program normally updates 
.blk before it is used again. If .blk®0, TT: 
gives ~ prompt and LP: gives form feed. 

(This is true for all .READ and .WRITE 
requests.) 

Request Format: 


R0 4 .area: 



USe L?m° gram needs to access the data read on the specified 
® .WAIT request should be issued. This ensures that the data 
has been read completely. If an error occurred during the transfer 
the .WAIT request indicates the error* 9 
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Errors s 

Code 

0 

1 

2 


Explanation 

Attempt to read past end-of-file 
Hard error occurred on channel 
Channel is not open 


Example: 

Refer to the .WRITE/.WRITC/.WRITW examples. 


.READC 

The .READC request transfers a specified number of words from the 
indicated channel to memory. Control returns to the user program 
immediately after the .READC is initiated. Execution of the user 
program continues until the .READC is complete, then control passes 
to the routine specified in the request. When an RTS PC is executed 
in the completion routine, control returns to the user program. 


Macro Call: 
where: 


.READC .area, .chan, .buff, .went, .ertn, .blk 

.buff is the address of the buffer to receive the 

data read. 


.went is the number of words to be read. 

.ertn is the address of the user's completion 

routine (refer to Section 9.2.8). 

.blk is the block number relative to the start of 

the file, not block 0 of the device. The 
monitor translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 


Request Format: 

RO 4 .area: 


10 .chan 


.blk 


.buff 


.went _ _^__ 

address of completion routine 


When entering a .READC completion function the following are true: 


1. RO contains the channel status word for the operation. If 
bit 0 of RO is set, a hardware error occurred during the 
transfer. The data may not be reliable. 


2. Rl contains the octal channel number of the operation. This 
is useful when the same completion function is to be used for 
several different transfers. 
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Errors: 

Code 

0 

1 

2 


Explanation 

Attempt to read past end-of-file 
Hard error occurred on channel 
Channel is not open 


Example: 

Refer to the .WRITE/.WRITC/.WRITW examples. 


•READW 


Tne .READW request transfers a specified number of 
indicated channel to memory. Control returns to the 
the .READW is complete or if an error is detected. 


words from the 
user program when 


Macro Call: .READW .area, .chan, .buff, .went, .blk 


where: .buff 


is the address of the buffer to receive the 
data read. 


.went 


is the number of words to be read. The 
number must be positive. 


is the block number relative to the start of 
the file, not block 0 of the device. The 
monitor translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 


Request Format: 


RO 4 .area: 


10 f . 


chan 


.blk 


.buff 

.went 


On return from this call, the C bit set indicates an error has 

occurred. if no error occurred, the data is in memory at the 

addr ® s ?» f 11 F / B system, the other job can be run while 
the issuing ]ob is waiting for the I/O to complete. 


Note: 

Upon return from any READ programmed request, RO will contain no 
information if the read is from a sequential-access device (for 
example, magtape). If the read is from a random-access device (disk, 
DECtape) RO will contain the actual number of words that will be read 
(.READ or .READC) or have been read (.READW). This will be less than 
the requested word count if an attempt is made to read past the end- 
of-file, but a partial transfer is possible. In the case of a partial 
transfer, the C bit is set and error code 0 is returned. Therefore, a 
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program should always use the returned would count as the number of 
words available. For example, suppose a file is 5 blocks long (i.e. , 
it has block numbers 0 to 4) and a request is issued to read 512 words, 
starting at block 4. The request is shortened to 256 words; no error 
• is indicated. Also note that since the request will be shortened to 
an exact number of blocks, a request for 256 words will either succeed 
or fail, but cannot be shortened. 


Errors: 

Code Explanation 

0 Attempt to read past end-of-file 

1 Hard error occurred on channel 

2 Channel is not open 

Example: 

Refer to the .WRITE/.WRITC/.WRITW examples. 


.RELEAS 


9.4.31 .RELEAS 

The .RELEAS request removes the handler for the specified device from 
memory. The .RELEAS is ignored if the handler iss 

1. Part of RMON (i.e., the system device), 

2. Not currently resident, or 

3. Resident because of a LOAD command to the Keyboard Monitor, 

.RELEAS from the foreground is always ignored, since the foreground 
can only use handlers which have been LOADed. 

Macro Calls .RELEAS .devname 

where: .devname is the pointer to the .RAD50 device name. 


Errors s 

Code Explanation 

0 Handler name was illegal. 
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Example: 

In the following example, the DECtape handler (DT) is loaded into 
memory, used, then released. If the system device is DECtape, the 
handler is already resident, and .FETCH will return HSPACE in RO. 

.MCALL . .V2..,.REGOEF,.FETCH,.RELEAS,.EXIT 

•.V2,, 

.RiftDEF 


START! .FETCH RHSPACE,ROTNAME I LOAD DT HANDLER 


BCB FERR 

I USE HANDLER 

.releas rotname 

8R START 

FERR! HALT 
DTNAMEI .RAO50 /DT / 
HSPACE! 


»NOT AVAILABLE 


I HARK DT NO LONGER IN 
I MEMORY, 

!DT NOT AVAILABLE 
!NAME FOR DT HANDLER 
IBESINNING OF HANDLER 
I AREA 


.END START 


.RENAME 

9.4.32 .RENAME 

The .RENAME request causes an immediate change of name of the file 
specified. An error occurs if the channel specified is already 
open. 

Macro Call: .RENAME .area, .chan, .dblk 


Request Format: 


RO 4 .area: 


4 

.chan 

.dblk 


The .dblk argument consists of two consecutive 
specifications. For example: 


.RAD50 device and 


.RENAME #AREA,#7,#DBLK ;USE CHANNEL 7 

BCS RNMERR ;NOT FOUND 


file 


DBLK: 


.RAD50 

/DT3/ 

.RAD50 

/OLDFIL/ 

.RAD50 

/MAC/ 

.RAD50 

/DT3/ 

.RAD50 

/NEWFIL/ 

• RAD50 

/MAC/ 
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The first string represents the file to be renamed and the device it 
is found on. The second represents the new file name. If a file with 
the same name as the new file name specified already exists on the 
indicated device, it is deleted. The second occurrence of the device 
name DT3 is necessary for proper operation, and should not be omitted. 
The specified channel is left inactive when the .RENAME is complete. 
.RENAME requires that the handler to be used be resident at the time 
the .RENAME request is made. If it is not, a monitor error occurs. 
Note that .RENAME is legal only on files which are on disk or DECtape. 
(.RENAMES to other devices are ignored.) 


Errors: 

Code Explanation 

0 Channel open 

1 File not found 

Example s 

In the following example, the file DATA.TMP on DTO is renamed to 
DATA.001: 


.MCALL ..V2..,.REGDEF,.FETCH,.PRINT 
•HCALL .EXIT,.RENAME 
«. V2.. 

.REGDEF 


PHBPACE,RNAMBIK > GE T HANDLER 
FERR I SOME ERROR 

#AREA,»0,»NAMBLK IDO THE RENAME 
RNMIRR I ERROR 


STARTl .FETCH 
BCS 

.RENAME 

BCS 

.EXIT 

FERRI .PRINT 
.EXIT 

RNMERRI .PRINT 
.EXIT 
AREA I ,BIKW 
NAMBLKI .RAO50 
, RAO50 
FMSGI .ASCII 
RNMSGI .ASCII 
.EVEN 

HSPACEl. 

.END 


FFMSG 

iRNMSC 

S 

/DT0OATA TMP/ 
/DT0DATA 001/ 
/FETCH?/ 
/RENAME?/ 


START 


IR00M FOR ARGS. 
1010 NAME 
INEW NAME 
I ERROR MESSAGES 
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.REOPEN 


9.4.33 .REOPEN 

The .REOPEN request reassociates the specified channel with a file on 
which a .SAVESTATUS was performed. The .SAVESTATUS/.REOPEN 
combination is useful when a large number of files must be operated on 
at one time. As many files as are needed can be opened with .LOOKUP, 
and their status preserved with .SAVESTATUS. When data is required 
from a file, a .REOPEN enables the program to read from the file. The 
.REOPEN need not be done on the same channel as the original .LOOKUP 
and .SAVESTATUS. 


Macro Call: .REOPEN .area, .chan, .cblk 

where: .cblk is the address of the five-word block where 

the channel status information was stored. 


Request Format: 


Errors: 

Code 

0 


RO 4 


.area: 


6 

.chan 

.cblk 


Explanation 

The specified channel is in use. 
been done. 


The 


REOPEN has not 


Example: 

Refer to the example following the description of .SAVESTATUS. 


9.4.34 .SAVESTATUS 


• SAVESTATUS 


The .SAVESTATUS request stores five words of channel status 
information into a user-specified area of memory. These words contain 
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all the information RT-11 requires to completely define a file. When 
a .SAVESTATUS is done, the data words are placed in memory, and the 
specified channel is again available for use. When the saved channel 
data is required, the .REOPEN request is used. 

.SAVESTATUS can only be used if a file has been opened with .LOOKUP. 
If .ENTER was used, .SAVESTATUS is illegal and returns an error. Note 
that .SAVESTATUS is legal only on files which are not on magtape or 
cassette. 

I Macro Call: .SAVESTATUS .area, .chan, .cblk 

where: .cblk is the address of the user memory block (5 

words) where the channel status information 
is to be stored. 


Request Format: 

RO 4 .area: 


. chan 


.cblk 


The five words stored are the five words normally contained in the 
channel area, as follows: 


I 


Word # 

1 


2 

3 

4 

5 


Contents 

Channel status word. The contents of the bits of 

this word are: 

Bit # Contents 

0 1 - a hardware error occurred on this 

channel. 

1-5 Index into monitor tables. This describes 

the physical device with which the channel is 
associated. 

6 1 - a .RENAME operation is in progress on the 
channel. 

7 1 - a .CLOSE operation must rewrite the 
directory (i.e., set when a .ENTER is done). 

8-12 Contains the directory segment number 

(1-37(8)) in which the current open file can 
be found. 

13 1 - An end-of-file was found on the channel. 

14 Unused. 

15 1 - This channel is currently in use (i.e., a 
file is open on this channel). 

Starting block number of the file. Zero for 

sequential-access devices. 

Length of file (in 256-word blocks). 

Data length of file; currently unused. 

Even Byte: I/O count. Count of how many I/O 

requests have been made on this channel. Odd Byte: 
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’?betweSfo r -°7) T* d ® ViCe associated with the channel 
While the .SAVESTATUS/.REOPEN combination is very useful, care must h* 

S5S? " " 3l " 9 In particu1 "' **» a 


1 . 


2 . 


J5l^tlH AV h S f ATUS H performed and the same file is then 
2£® ted befo £® it is reopened, it becomes available as an 
empty space which could be used by the .ENTER command. If 

“Jed “1^^?°"”' t " e °° nten “ ° £ £ile supposedly 

™t h °u! h - hS device handler for the required peripheral need 
not be in memory for execution of a .REOPEN, if the handler 
is not in memory when a .READ or .WRITE is executed, a fatal 
error is generated. ' Iacai 


Errors: 


C° de Explanation 

1 The file was opened via .ENTER, or is a magtape or 

cassette file, and a .SAVESTATUS is illegal. 

Example: 


One of the more common uses of .SAVESTATUS and .REOPEN is to 

J£H!£ii dat ?n a «i direCtory access motion and code at one place in the 
program. All files necessary are opened and their status saved, then 

. ar ® re ~°pened one at a time as needed. USR swapping can be 
minimized by locking in the USR, doing .LOOKUPS as needed, usina 
.SAVESTATUS to save the file data, and then .UNLOCKing the USR. 


In the program segment below, three input files are specified in the 
command string; these are then processed one at a time. 

.MCAIL ..V2,.,.RtGDEF,.CSIGEN,.SAVESTATUS,.REOPEN 
.MCALL .READ..EXIT 
• •V2.. 

.REGOEF 


START! MOV RAREA.R5 

.C8IGEN RD8PACE.RDEXT 

MOV R0.BUFF 


»get input files 

(save POINTER to free core 


.SAVESTATUS R5,#S,RBLOCK1 |SAVE FIRST INPUT FILE 
.SAVESTATUS R5,#«,*BLQCK2 ;3AVE SECOND FILE 
.SAVESTATUS R5,#5,RBL0CK3 >SAVE THIRD FILE 


MOV RBL0CK1.R4 

PROCESS! .REOPEN R5,#0,R4 IREOPEN FILE ON 

I CHANNEL 0 


DONE; 


.READ R5,#0,BUFF,COUNT,BLOCK >PR0CESS FILE ON CHANNEL 0 


ADD #12,R4 

CMP R4,PBL0CK3 


(POINT TO NEXT SAVESTATUS BLOCK 
(LAST FILE PROCESSED? 
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BLOB 

.EXIT 

PROCESS 

|NO • DO NEXT 

BLOCK 11 

.WORD 

0,0,0,0.B 

fNEMORV BLOCKS FOR 

BLOCKS 1 

, WORD 

0,0,0,0,0 

ISAVESTATUS INFORMATION 

BL0CK3I 

, WQRO 

0,0,0,0,0 


AREA 1 

,BLKW 

10 


BUFFI 

.WORD 

0 


BLOCKI 

.WORD 

0 


COUNTl 

.WORD 

m. 


DEXTI 

03PACfc» 

, WORD 

'.END 

0,0,0,0 

START 



. S DAT/SDATC/SDATW 


9.4.35 .SDAT/.SDATC/.SDATW 

These requests are used in conjunction with the .RCVD/.RCVDW/.RCVDC 
calls to allow message transfers with RT-11. .SDAT transfers can be 

considered similar to .WRITE requests in which data transfer is not 
from a peripheral, but from one job to another. Additional I/O queue 
elements should be allocated for buffered I/O operations in .SDAT and 
.SDATC requests (see .QSET). 

.SDAT 

Macro Call* .SDAT .area, .buff, .went 

where: .buff is the buffer address of the beginning of the 

message to be transferred. 

.went is the number of words to transfer. 


Request Format: 


Errors: 
Code 
0 


RO # .area: 


25 0 


unused 

.buff 


.went 


Explanation 
No other job exists, 
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Example: 

See the example following .SDATW. 


.SDATC 

Macro Calls .SDATC .area, .buff, .went, .ertn 


where: .buff 

.went 

.ertn 


is the buffer address of the beginning of the 
message to be transferred. 

is the number of words to transfer. 

is the address of the completion routine to 
be entered when the message has been 
transmitted (refer to Section 9.2.8). 


Request Format: 


RO 4 .area: 


25 0 


unused 


.buff 


.went 


.ertn 


Errors: 
Code 


Explanation 
No other job exists. 


Example: 

See the example following .SDATW. 


.SDATW 

Macro Call .SDATW 
where: .buff 


.area, .buff, .went 

is the buffer address of the beginning of the 
message to be transferred 


.went 

Request Format: 

RO 4 .area: 


is the number of words to transfer 


25 


unused 


.buff 

.went 
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Errors: 

Code Explanation 

0 No other job exists. 

Example: 


In this example, the job first sends a message interrogating the other 
job about the status of an operation, and then looks for an 
acknowledgement from the job. 


,MCA|.L ..V2,.,.REGDEF,.BOAT#.RCVD,.MWAIT,.PRINT#.EXIT 

• .V2 . » 

.REGDEF 


STARTl 

MOV WAREA#R5 (SET UP EMT BLOCK 

.BOAT R5»iSBUFF # FMLGTM I ASK HIM A QUESTION 
BC3 NO JOB ( NO OTHER JOB AROUND 1 

(MISCELLANEOUS PROCESSINB 


.RCVD R5# #BUFF2 # #20 
.MWAIT 

MOV #BUFF2*2,Rl 

CMPB (Rl)*»i*V 
BNE PRNE6 

.PRINT RPOSACK 


(RECEIVE 20 DECIMAL WOROS 
(WAIT FOR ACKNOWLEDGE. 
(POINT TO ACTUAL ANSWER. 
(IS FIRST WORO Y FOR YESt 
(NEGATIVE ACKNOWLEDGE 


.EXIT 


PRNEGI .PRINT 
.EXIT 

8BUFFI .ASCII 
MLGTM*,«3BUFF 
BUFF2I .WORD 
.BLKW 


iNEGACK (NEGATIVE ON OUR INQUIRY 

/IS THE REQUIREO PROCESS GOINGT/ 

0 (ACTUAL LENGTH IS HERE 

20, (SPACE FOR 20, WORDS 


NOJOB I .PRINT 
.EXIT 

NEGACKI .ASCII 
POSACKI .ASCII 
NJMSGI . A3CIZ 
.EVEN 
AREA I .BLKW 


FNJMSG 

/NEGATIVE ACKNOWLEDGE/ 
/POSITIVE ACKNOWLEDGE/ 
/NO JOB/ 

10 . 


,EN0 START 


.SETTOP 


9.4.36 .SETTOP 


The .SETTOP request allows the user program to 
address be specified as a program's upper 


request that a new 
limit. The monitor 
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determines whether this address i<, ^ 

swap is necessary when thl W * ether °r not a memory 

program specified an upper limit hpi nu ., ^ U1 f ed * For instance, if the 
sapping is neoessaST a “ re3s ° £ ^R, „o 

the background specifies a hiah lim-H- 3 n °!r over iaid. if .SETTOP from 
US* and a SET uIr msw hit £?““«“» 0,6 add * a3 “ ° £ S 

required. Section 9.2.5 gives details on a f 9iven, a memory swap is 
in memory and how to optimize the ?SETTOP. d stemming where the USR is 

On return from .SETTOP, both nn ana *w 

contain the highest memory address® alloca£ , 1 ° cation 50 (octal) 
requested an address higher than the hioh«f S for use * If the job 
for the requesting job/it isJK2. ±3 le * al 

Macro Call: .SETTOP .addr 


where: .addr 


Notes s 


is the address of the word 
following the free area desired. 


immediately 


1 . 


2 . 


Errors s 
None. 


A program should never do a j 

upper limit is the address d a f s ^ me that its new 
examine the returned contents Zt must alwa ys 
determine its «otJS^hiyJd£.s^ “ 10Cation 50 to 


addr ess r in°R 0 ^ but onl^in‘word °50 ^ ^ the high 

be used P as^he Ssolutl upper limit^if^hi ° r J 0 ca f ion 50 
exceeded, vital narts r -J-imit. if this value is ever 

the system integrity will be violated ?® 7 *** destr °y ed ' and 


Example: 

Following is an example in two Darts «• 

small background job (i.e., one with fr BO he fl f st ind i ca tes how a 
USR) can be assured of reserving space ud itself and the 

This in effect gives the job all the 1 n °^ includin U the USR. 

USR to become non-resident. pa e Xt Can wlt hout causing the 

apLrby n m«Rl“ ^ " aXi " ,U " ’ aomt of 


I) 


•MCALL 

■ •V2.. 

•REGDEF 


• *V2t,«.REGDEF,.SETTOP,.EXIT 


START I 

RM0N»5R 

USR*26S 


I POINTER TO START OF RESIDENT 
I OFFSET FROM RESIDENT TO POINTER 
I WHERE USR WILL START. 
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II) 


MOV 

##bmon.R1 

MOV 

USPCPlY »P0 

TST 

.(pet 

.SETTOP 

MOV 

R0,HlCORE 

.SETTOP 

#•2 

MOV 

R0,HlCORE 

.EXIT 

.WORD 

0 

.ENO 

START 


fSTART OP »MON TO *1 

;ssi u ^?s5?;t u :s-s 0 sSt >. «. 

Jm°CO»T«I»I ‘It "‘ sm *» d » E55 

I THAT WAS RETURNED. 

jIF WE ASK FOR A VALUE GREATER 
I THAN START OF RESIDENT# WE 
I WILL GET BACK THE ABSOLUTELY 
|HIGHEST USABLE ADORESS. 

I THAT IS OUR LIMIT NOW 


non-resident* Tn^th^“inToS^ « 

value just below the USR. t , rf -t-hp 

Caution should be used th/usTis normally’ positioned 

re? r pa« ^limit value returned^ byhe^ 

actually be low ® r Q^a^destroyed. The example in Section 

^ h 5 %rofs 1 °ho„°to t in= U ludl SSSTtSS -?1 avoid this situation. 



^ ^ 37 SFPA 

.SFPA allows users with f ioatmg point hardware (FPP on 1 / po i n t 

on 11/40) to set trap addresses tobejn tered^hen^ ^ & ^ 

exception occurs. If no ^ a ?m-FP TRAP occurs, and the job is 

point (FP) exception occurs, a m A ““ jr 

aborted. 


Macro Call: 
where: 


.SFPA .area, .addr 

addr is the address of the routine to 

when an exception occurs. 


be entered 


Request Format: 

R0 4 .area: 


30 


1.addr 


Notes: 

1. 

2 . 


In the F/B environment, an addres. value of l indioates^that 

™ r;SS MW 


Monitor is equivalent to an address of 0. 


July 1975 


9-84 














Programmed Requests 


3. 


4. 


Errors: 
None. 


When the user routine is activated u- 

re-execute an .SFPA reouest « * 1 ! . is necessary to 

traps when any one is serviced' ft doen^h^^ i ? hibits user 

exceptions. in ^ in ^ te £T ^ ^ 

executed ^by "V’UnS/'^oS* JSSSS^ST" '. <SP) U 

S lne ; f( Th S “tacr p b e? utin , e ^ ST st«S 

ten if Fp“ h arSa« L"IvSiSlf *F‘ 

configuration word in the monitor (see Seotion *?^^? 9 th ® 


Example: 

This example sets up a user PP trap address. 

-"CALL ..V*..,.*ERDFF,.$FPA,.FXTT 


•• V 2,, 

.REGOEF 


STARTf 


• SFpA 
.EXIT 


FPTRAR! 


*APEA,#FP7R A p 


AREA I 


MOV 

.SFPA 

MOV 

RTI 

.8LKW 

.EN 0 


R0,*fSP) 

*A»EA,*ppxp A p 

fSF)+,R0 


10 

START 


USED BV .SFPA 

irestqre RP 



9.4.38 .SPFUN 

handlers q io S do divice-dlpenS^funSions^ 11 suc^T 63 magtape 

allow^reading a^d^Jiting^f^bsol^rLftoJs^ USed f with diskette | 

m Appendix H.) absolute sectors; specific information is 


Macro call, .SPFUN .area, .chan, .code, .buff, .went. 


where: .code 


.blk, .ertn 


is the numerical code of the function 
performed 


to be 
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.buff 
.crtn 


is the buffer address; this parameter must be 
set to zero if no buffer is required. 

is the entry point of a completion routine. 
If left blank, 0 is automatically inserted. 


Request Format: 


RO $ .area: 


.blk 


32 .chan 


.buff 


.went 


code| iTT 


.crtn 


ri e i“s«? n o n is t h e in ch t J;“r 1 d e„r c .r t srt 

immediately to the user program. • .. ^ taken as a completion 

operation is completed. If .crtn-N, it is tanea “ “ * 

routine 6 address to be entered when the operation rs complete. 

The available functions and their codes are: 

Function MT £2 


Forward to last file 
Forward to last block 
Forward to next file 
Forward to next block 
Rewind to load point 
Write file gap 
Write EOF 
Forward 1 record 
Backspace 1 record 
Write with extended 
file gap 
Offline 


373 

377 

376 

375 

374 
372 


377 

376 

375 

374 

373 

372 


To use the .SPFUN request, the handler must be in memory and a channel 
associated with a file via a .LOOKUP request. 

Refer to Appendix H for details of MT and CT handlers. 

Errors: 

Errors ere detected in the same way as for the .READ/.KADC/.READW 
requests. Refer to Section 9.4.30 for details. 

Example: 

The following example rewinds a cassette and writes out a 256 word 
buffer and then a file gap. 

.MCAU ..V2..,.REG0EF,.FETCH,,LOOKUP,.5PFUN,,WRITW 

, MCALL .EXIT,.PRINT,.WAIT,.CLOSE 

..vs.. 

,REGOEF 


STARTl 


.FETCH iH3PC,*CT 


t GET A HANDLER 
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BCS FERR (FETCH ERROR 

.LOOKUP •AREA.FR,»CT (LOOK IT UP ON CHANNEL 4 

BCS LKERR (LOOKUP ERROR 

.SPFUN #AREA,#4,#J73,#P(REWIND SYNCHRONOUSLY 



BCS 

BPERR 


HOV 

• 3.R3 


.WRIT* 

•AREA ,#4. iBUFF 


BCS 

WTERR 


a SPFUN 

•AREA, *4, *372# 


.PRINT 

• DONE 


.WAIT 

• 4 


.CLOSE 

.EXIT 

• 4 

ARE A 1 

.BLKW 

10 

FERRI 

.PRINT 

.EXIT 

• F MSG 

LKERR1 

.PRINT 

.EXIT 

•LKM3G 

3PERRI 

.PRINT 

.EXIT 

•SPM86 

wterri 

.PRINT 

.EXIT 

•WTMSG 

DONE 1 

.ASCIZ 

/ALL OONE/ 

FMSGI 

• ASCII 

/FETCH?/ 

LKM9GI 

.ASCIZ 

/FILE?/ 

9RMSGI 

.ASCIZ 

/SPECIAL FUNCT 

WTMSGI 

.ASCIZ 

.EVEN 

/WRITE ERROR/ 

CTI 

,RAO50 

/CT / 


.WORD 

0.0.0 

BUFFI 

.BLKW 

25*. 

BLKI 

.WORD 

0 

HSPCs, 

,EN0 

START 


IAN ERROR OCCURRED. 

ICOUNT 
(BLOCK 0, 

.R2S6..BLK 

*0,,*i I‘SYNCHRONOUS FTLF RAP 

(WAIT FOR DONE 
I CLOSE THE FILE 


ION ERROR/ 


.SPND/.RSUM 


9.4.39 .SPND/.RSUM (F/B only) 

The .SPND/.RSUM requests allow a job to control execution of its 
mainstream code (that code which is not executing as a result of a 
completion routine). .SPND suspends the mainstream and allows only 
completion routines (for I/O and mark time requests) to run. .RSUM 
from one of the completion routines resumes the mainstream code. 
These functions enable a program to wait for a particular I/O or mark 
time request by suspending the mainstream and having the selected 
event's completion routine issue a .RSUM. This differs from the .WAIT 
request, which suspends the mainstream until all I/O operations on a 
specific channel have completed. 

.SPND 


Macro Call: .SPND 


where: RO 
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. RSUM 


Macro Call: .RSUM 
where: RO # 

Notes: 


1. The monitor maintains a suspension counter for each job. 

This counter is decremented by .SPND and incremented by 
•RSUM. A job will actually be suspended only if this counter 
is negative. Thus, if a .RSUM is issued before a .SPND, the 
latter request will return immediately. 

2. A program must issue an equal number of .SPNDs and .RSUMs. 

3. A .RSUM request from the mainstream code increments the 

suspension counter. 

4. A .SPND request from a completion routine decrements the 

suspension counter, but does not suspend the mainstream. If 
a completion routine does a .SPND, the mainstream continues 
until it also issues a .SPND, at which time it is suspended 
and will require two .RSUMs to proceed. 

5. Since a .TWAIT is simulated in the monitor using suspend and 
resume, a .RSUM issued from a completion routine without a 
matching .SPND may cause the mainstream to continue past a 
timed wait before the entire time interval has elapsed. 

6. A .SPND or .RSUM, like most other programmed requests, may be 
issued from a user-written interrupt routine if the .INTEN/ 
.SYNCH sequence is followed. All notes referring to .SPND/ 
.RSUM from a completion routine also apply to this case. 


Errors: 

None. 

Example: 

In this example, the program starts a number of read operations and 
suspends itself until at least two of them are complete. 

.MCALL ..V2,,,.REGDEF,.SPND,.RSUM,,RE ADC,.EXIT#.LOOKUP 

.mcall .PRINT,,*AIT 

..V2.. 

.RECDEF 

START: 

.LOOKUP PAREA,*2,PFILE2 
BCS IS 

.LOOKUP PAREA,*3,PFJLE3 
BCS IS 

•LOOKUP PAREA, *U, PFILE4 
BCC 3S 
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ill 

.PRINT 

.EXIT 

I2S 

291 

lit 

.ASCXZ 
.even 

/LOOKUP ERROR/ 



MOV 

MOV 

• 2* R8VCTR 

BAREA.R5 

IWAIT FOR 2 COMPLETIONS 


• READC 
BCS 

R5,«2,#BUFl,COUNT I,BCROUTN,BLOK 1 

ERROR 


.READC 
BCS 

R5,B3,BBUF2,C0UNT2,BCR0UTN,BL0K2 

ERROR 


• READC 

BCS 

,3PN0 

.WAIT 

.WAIT 

.WAIT 

.EXIT 

R5,B4,BBUF3,C0UNT3,BCR0UTN,BL0K3 

ERROR 

#2 

13 

#4 

CROUTNI 

A»L 

Rl 

i double channel b for INOEXINC 


INC 

DONEFL(Rl) 

|R1»CMANNEL that is done 

1 SET A FLAG SAVING SO, 


ROR 

R0 

1 ANY ERRORS? 


AOC 

ERRFLG(Rl) 

»IF CARRY SET, SET ERROR FLAG FOR CHANNEL 


DEC 

RSVCTR 

1 ARE WE THE SECOND TO FINISH? 


BNI 

.RSUM 

IS 

1 NO 

IYES, START UP 

1*1 

RTS 

PC 

ERROR 1 

.PRINT 

.EXIT 

BRDMSG 


ROMSGl 

.ASCII 

.EVEN 

/READ ERROR/ 


ARE A 1 

.BLKW 

10 


R8VCTRI 

.WORD 

0 


CQUNT1I 

.WORD 

256, 


C0UNT2I 

.WORD 

256. 


COUNTS 1 

.WORD 

256, 


BLOK 11 

.WORD 

0 


BuOK2l 

.MONO 

0 


BLOKS 1 

.WORD 

0 


PILE2I 

.RAO50 

/OK TEST2 TMP/ 


PILESI 

,RAD50 

/OK TESTS TMP/ 


FILE4I 

, RAO50 

/DK TEST4 TMP/ 


OONEPLl 

.WORD 

0,0,0 


ERRFLGl 

.WORD 

0,0,0 


BUF1I 

.BLKW 

256, 


BuF2I 

.BLKW 

256, 


BUF3: 

.BLKW 

.END 

256, 

START 
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.SRESET 


9.4.40 .SRESET 

The .SRESET (software reset) request performs the following functions: 

1. Dismisses any device handlers which were brought into memory 
via a .FETCH call. Handlers which were loaded via the 
Keyboard Monitor LOAD command remain resident, as does the 
system device handler. 

2. Purges any currently open files. Files opened for output 
with .ENTER will never be made permanent. 

3. Reverts to using only 16 (decimal) I/O channels. Any 
channels defined with .CDFN are discarded. A .CDFN must be 
reissued to open more than 16 (decimal) channels after a 
.SRESET is performed. 

4. Resets the I/O queue to one element. A .QSET must be 
reissued to allocate extra queue elements. 

5. Clears completion queue of any completion routines. 


Macro Call .SRESET 
Errors: 

None. 

Example: 

In the example below, .SRESET is used prior to calling the CSI to 
ensure that all handlers are removed from memory and the CSI is 
started with a free handler area. 

.MCALL .,V2,.,.REGDEF,.CSIGEN,.SRESET, .EXIT 
• • V2,, 

.KESOEF 


STARTl 


• CSIGEN • D3PACE,*DE)(T,#0 I GET COMMAND STRING 
MOV R0,BUFFER |R0 POINTS TO FREE MEMORY 


DONE I .SRESET 

SR START 


I RELEASE HANDLERS, DELETE 
TENTATIVE FILES 
I A NO REPEAT PROGRAM, 
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OCX TI ,H0RD 

BUFFERl 0 
0SPACE», 


0,0,0,0 


.cnd START 


INO DEFAULT EXTENSIONS 
f START OF HANDLER AREA, 


”sKlN; SR ft ET is aa pM3mr t h!? f SS^ pri r to “» -cona call of 

handler over one that the monlto^thj J2 d comrnan '? 3trin g would load a 
command line. ought was resident from the first 



9.4.41 .TLOCK 

USR? CK it IT similar /B to YSt LOCK° i^that gain ° wnershi P of the 

returns with the USR in memory. However if f a S iob e atf Ul % the < - USer j ° b 

the USR while the other job i! 1'i a 3ob attempts to .LOCK 
suspended until the USR is free with TTnrx*' guesting 3° b is 
available, control returns i^dia^y c bit Lt°f R n0t 

the .LOCK request failed. y tne C bit set to indicate 

Macro Call: .TLOCK 

I^-jo^afSlSd! al S T j ScK° ru ?? in ’' °nly one 

automatically suspended^* tha^lS'^ t£\ys««? * 

Request Format: 


RO: ^ area: 7 0 


Errors: 



Example: 


Explanation 

USR is already in use by another job, 


it fxec^g. BX ^ P ll 'fai?s U ?o r ae? 0 Srii^R e ?f thS ° SR f ° r a sub "30b 
and runs another sub-job. This ^tvDef^nf 311 At s “ spend f that sub-job 
schedule several suh-^switS^a h^grolud We^rofmd pTo^ 


.MCALL 
••V2,, 

.regdef 


..V2..,,REGDEF,.TLOCK,,LOOKUP,.UNLOCK,.EXIT,.print 


STARTl 
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,TLOCK 
BCS 

.LOOKUP 

BCS 

.UNLOCK 


8U8PN0 

#AREA,#«»*J1NAM 

LKERR 


I SET THE U8P 

If ailed. SUSPEND SUB-JOB 
I LOOKUP A PILE 

|RELEASE USB 


.EXIT 


SUSPNDt JSB PC.SP8J0B 

JSB PC»8CHED 


AREA* 

,BLKM 

J1NAHI 

.RADS0 

LKERRI 

.PRINT 


.EXIT 

LKHSGl 

.ASCII 


• EVEN 

SP8J0BI 

RTS 

SCHEDI 

RTS 


10 

/OK TEST1 TMP/ 
«LKHS6 

/LOOKUP ERROR/ 

PC 

PC 


I SUSPEND SUB-JOB 
|AND SCHEDULE NEXT USER 


.END START 


.TRPSET 


9.4.42 .TRPSET 

.TRPSET allows ^euserjob tointercept^rap^t^^and 10 i-tead^of 

having the job aborted with a ?MTRA^TO 4 o U8er -specified routine 
If .TRPSET is in effectwhenatrap occurs. routine determines 

is entered. The sense of the C bit on entry to^ ^ set indi cates 

ftfap^o^Sr^r^er'roiti^sUld exit via an RTI instruction. 
Macro Call* .TRPSET .area, .addr 


where t •addr 


is the address of the user's trap routine. 
If an address of 0 is specified, the user s 
trap interception is disabled. 


Request Format* 

R0 * .area* 


1LQ 


.addr 


Notes: 

an RTI is to reissue the .TRPSET request. 
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Errors: 

None, 

Example: 

occur s^prints^rT'appropriate When the tra P 

.MCAU ,.V2..,.REGDEF,.TRPSET,.EXIT,.PRINT 
.Regoef 

STARTl 


.TRPSET PAREA,#TRPLOC 

MOV *101,R0 

T»T (R0) * 

.WORD 37 
.EXIT 


I8ET TO PRODUCE A TRAP 
f THIS HILL TRAP TO 4. 

* THIS WILL TRAP TO 10, 


trplpci mov 

BCS 


.PRINT 



BR 

ill 

.PRINT 

SSI 

.TRPSET 

MOV 


RTI 

AREA I 

.SLKW 

TRP4I 

.A SC IZ 

TRP10I 

.A SC IZ 
.even 


.end 


R 0.-(SP) 

IS 

#TRP4 

2S 

PTRP10 
• AREA,# TR 
fSP)*,R0 


10 

/TRAP T0 4/ 
/TRAP T0 10/ 


IRPI U$FD BV PMTS 
|C SET ■ TRAP TO 10 
ITRAP TO 4 

ITRAP TO 10 
I RESET TRAP ADDRESS 

irfstore ROi 


START 



9.4.43 .TTYIN/TTINR 

terminai qU to tS the e user * 3 proorS*" 8 ^ characters from the console 
right-justified (even byte) in RO. * character thus obtained appears 
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The expansion of .TTYIN iss 


EMT 340 
BCS .-2 

while that for .TTINR iss 
EMT 340 

If no characters ?^ 1 ^® s c a J® t a ggt lab The W implication 3 of these calls is 
return is made with the C hit s for a character/line to 

usefcan either wait or continue protecting using 

.TTINR. 

Macro Calls: .TTYIN .char 


.TTINR 

where: .char 


is the location where the character in R0 is 
stored. If not specified, the character is 

left in R0. 

rllJA ^ oarS bii sU unless bit 6 of the Job Status Word was on 
when the request was issued (see below). 

by^bit^ll^of^the'^Job^StatusO^Word^ixf^bit P 12*- SSomaSl/Sis 

performed^ 2 In this mode, the following conditions apply. 


1. 


The monitor echoes all characters typed; 
characters are converted to upper case. 


lower 


case 


2 . 


CTRL U (tU) and RUBOUT perform line deletion and character 
deletion, respectively. 

3 - struckSeforScharactersSSth^current fine^ .SaiSEe to 

SI P ^e%pS en a?f r p2sero^-^-one y S d 4ne°!;S“p?ograS;" 

Slh cSIiaS IetuS and line feed are passed to the program. 

4. ALTMODEs (octal codes 175 and 176) are converted to ESCAPES 
(octal 33)• 

If bit 12-1, the console is in special mode. The effects ares 

1. The monitor does not echo characters typed except for CTRL C 
and CTRL O. 


2 . 


3. 


CTRL U and RUBOUT do not perform special functions. 
Characters are immediately available to the program. 


4. No ALTMODE conversion is done. 

rt^rbSineSissrin srsa 
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way. Bit 12 
cleared when 


in the JSW must 
control returns 


be set by the 
to RT—11. 


user program. 


This bit is 


CTRL F and CTRL B are not affected by 
monitor always acts on these characters 


the setting of bit 


12 . 


The 


CTRL S and CTRL Q are intercepted by the monitor (unless, under the 
F/B monitor, the SET TTY NOPAGE command is issued). 


Under the F/B Monitor, if a terminal input request is made and no 
character is available, job execution is blocked until a character is 
ready. This is true for both .TTYIN and .TTINR, and for both normal 
and special modes. If a program really requires execution to continue 
and the carry bit to be returned, it must turn on bit 6 of the JSW 

the • TTI " R reqUeSt ' Bit 6 ia cleared when „ 


Errors: 

Code Explanation 

0 No characters available in ring buffer. 

Example: 

Refer to the example following the description of .TTYOUT/.TTOUTR. 


.TTYOUT/.TTOUTR 


9.4.44 .TTYOUT/.TTOUTR 

These requests cause a character to be transmitted from RO to the 
is n tha? * e *T* lnal * The difference, as in the .TTYIN/.TTINR requests, 
^™i£ tt 5 here 18 no room for the character in the monitor's buffer, 
*? T ^ 0UT request waits for room before proceeding, while the 
.TTOUTR does not wait for room and the character in RO is not output. 

Macro Calls: .TTYOUT .char 


where: 


.TTOUTR 

.char 


is the location containing the character to 
be loaded in RO and printed. if not 
specified, the character in RO is printed. 
Upon return from the request, RO still 
contains the character. 

If t ^ ec ^ rr Y bit i s set when execution of the .TTOUTR reauest is 
completed it indicates that there is no room inthebuffer^dtha? 

° ha ff Cter J' as OUtpu ^.* Under F/B Monitor, .TTOUTR normally does 
not return the carry bit set. Instead, the job is blocked until room 
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is available in the output buffer. If a job really requires execution 
to continue and the carry bit to be returned, it must turn on bit 6 of 
the Job Status Word (location 44) before issuing the request. 


The .TTINR and .TTOUTR requests have been supplied as a help to those 
users who do not wish to suspend program execution until a console 
operation is complete. With these modes of I/O, if a no-character or 
no-room condition occurs, the user program can continue processing and 
try the operation again at a later time. 


Note: 

If a foreground job leaves bit 6 on in the JSW f any further foreground 
.TTYIN or .TTYOUT requests will cause the system to lock out the 
background. Note also that each partition has its own JSW, and 
therefore can be in different terminal modes independently. 

Errors: 

Code Explanation 

0 Output ring buffer full. 

Example: 


As an example of the various terminal requests, the following program 
is coded in two ways. The program itself accepts a line from the 
keyboard, then repeats it on the terminal. 

The first example uses .TTYIN and .TTYOUT, which are synchronous. The 
monitor retains control until both requests are satisfied, hence there 
is no time available for any other processing while waiting. 


.MCALL ..V2..,.REGDEF,,TTYIN,.TTYOUT 
,.V2.. 

.REGDEF 


START! 

MOV 

•BUFFER,Rl 


clr 

R2 

INLOOPI 

.ttyin 

(Rl)* 


INC 

R2 


CMPB 

•12,R0 


BNE 

INLOOP 


MOV 

•BUFFER,Rl 

OUTLOOP! 

.TTYOUT (Rl)* 


DEC 

R2 


BEQ 

START 


BR 

OUTLOOP 


I POINT R1 TO BUFFER 
'CLEAR CHARACTER COUNT 
IREAD CHAR INTO BUFFER 
I BUMP COUNT 
'WAS LAST CHAR-LFT 
'NO-GET NEXT 
'YES-POINT RI TO BUFFER 
IPRINT CHAR 
'DECREASE COUNT 
'DONE IF COUNT • 0 


BUFFER*. 

.END START 


Rather than wait for the user to type something at INLOOP or wait for 
the output buffer to have available space at OUTLOOP, the routine can 
be recoded using .TTINR and .TTOUTR as followss 
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.MCALL ..Va.,,.REGOEF,.miN,.TTYnUT 
.REGOEF 

.MCALL .TTINR,.TTOUTR,.EXIT 


START/ 

MOV 

OBUFFER.Rt 


CLR 

R2 


BIS 

#100,##«4 

INLOOP/ 

.TTINR 



BCS 

NOCHAR 

CHRINZ 

movb 

R0. (Rl) + 


INC 

R2 


CMPB 

R 0 » #12 


BNE 

INLOOP 

OUTLOOP: 

MOV 

*BUFFER,R1 

S MOVB 

(Rl),R 0 


.TTOUTR 

BCS 

NOROOM 

CHROUT/ 

DEC 

R2 


BED 

START 


INC 

Rl 


BR 

OUTLOOP 

NQCHAR! 

.TTINR 

BCC 

CHRIN 


/POINT R 1 TO BUFFER 
ICLEAR CHARACTER COUNT 
IWE REALLY WANT CARRY SET 
I SET CHAR FROM TERMINAL 
INONE AVAILABLE 
»PUT CHAR IN BUFFER 
UNCREASE COUNT 
I has LAST CHAR s LF? 

/ NO-GET NEXT 
I YES-POINT R 1 TO BUFFER 
/PUT CHAR IN R 0 
/TYPE IT 

t NO ROOM in OUTPUT BUFFER 
/ DECREASE COUNT 
/DONE IF COUNT «0 
/ BUMP BUFFER POINTER 
fAND TYPE NEXT 


/PERIODIC CHECK FOR 
/character availability 
/ GOT ONE 


(code to be executed 
while waiting) 


BR NOCHAR 

noroomz 


MOVB (Rl),R 0 

.TTOUTR 

BCC CHROUT 

(code to be ex 
while waiting) 

TYPEITl BIC # 100,##44 


.TTYOUT (Rl) 

BIS #100 ,##44 

BR CHROUT 


/PERIODIC ATTEMPT TO TYPE 
/CHARACTER 

I SUCCESSFUL 


/MUST CLEAR THIS BIT 
ISO hang WHILE 
/waiting for room, 

I PUT CHAR 
/RESTORE NO-WAIT 


buffer/ .blkw jo®, 

•END START 
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.TWAIT 


9.4.45 .TWAIT 


The .TWAIT request suspends the user's 
time. .TWAIT requires a queue element 

when the .QSET request is executed. 


job for an indicated length of 
, and thus, should be considered 


Macro call: .TWAIT .area, .time 


where: .time 


is a pointer to two words of time 
(high-order first, low-order second). 


Request Format: 

RO => .area: 


24 

0 

.time 


Note: 


Since a .TWAIT is simulated in the monitor using suspend 
. RSUM issued from a completion routine without a matching 
cause the mainstream to continue past a timed wait before 
time interval has elapsed. 


and resume, a 
.SPND may 
the entire 


Errors: 

Code Explanation 

0 No queue element was available. 


Example: 

.TWAIT can be used in applications where a program must be only 
activated periodically. This example will 'wake up every 10 seconds 
to perform a task, and then 'sleep' again. 

F,.TWAIT,,QSET,.EXIT,.PRINT 


/SET UP T EXTRA ELEMENTS 
/ SET R0 TO THE ARG, BLOCK 
|G0 TO SLEEP FOR 10 SECONDS 
|N0 QUEUE ELEMENT? 

100 SOMETHING HERE 
I AND THEN CYCLE 
/SPACE FOR 7 ELEMENTS 



.MCALL 
• • V2,, 

,REGDEF 

•.V2..,. REI 

GO 1 

.QSET 

PQAREA,#7 

START: 

MOV 

.TWAIT 

#EMTLST,R0 


BCS 

NOQ 


JSR 

PC,TASK 


BR 

START 

QAREAI 

.BLKW 

7*7 

EMTLSTI 

.BYTE 

0,24 


.WORD 

TIME 

TIMEI 

TASKI 

.WORD 

0,18.*60. 


M0 

) 

/ 


SECOND INTERVALS 


January 1976 


9-98 













Programmed Requests 



INC 

MPTR 


BIT 

•1,MPTR 


BEQ 

IS 


•PRINT 

• MSG 


NTS 

PC 


.PRINT 

• MSG 1 


RTS 

PC 

MPTRl 

. WORD 

0 

HSGI 

■ ASCIZ 

/TICK/ 

MSG l 1 

.ASCII 

.EVEN 

/TOCK/ 

NOQl 

.EXIT 



.END 

GO 


.WAIT 


9.4.46 .WAIT 

The .WAIT request suspends program execution until all input/output 
requests on the specified channel are completed. The .WAIT request 
combined with the .READ/.WRITE requests makes double-buffering a 
simple process* 

.WAIT also conveys information back through its error returns. An 
srror is returned if either the channel is not currently open or if 
the last I/O operation resulted in a hardware error. 

Macro Calls .WAIT .chan 


Note: 

In a F/B system, executing a .WAIT when I/O is pending causes that job 
to be suspended and the other job to run, if possible. 


Request Formats 


0 


.chan 


Errors s 


Code Explanation 

0 Channel specified is not open. 

1 Hardware error occurred on the previous I/O operation 

on this channel. 


These error codes make the .WAIT request useful in checking channel 
status. 
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Example: 

For an example of .WAIT used for I/O synchronization, see the examples 
in the next section. 

An example of the use of .WAIT for error detection is its use in 
conjunction with .CSIGEN to determine which file fields in the command 
string have been specified. For example , a program such as MACRO 
might use the following code to determine if a listing file is 
desired. 



• MC ALL 
. a V2 . . 

, REGDEF 

.. V2 .. . . REGDEF 

, .WAIT,.CSIGEN,.EXIT 

STARTl 

,CSIGEN 

•DSPACE,*DE XT. 

#0 |PROCESS COMMAND STRING 


.WAIT 

*0 

ICHECK FOR FILE IN FIRST FIELD 


BC6 

nobinary 

|N0 binary DESIRED 

NOBINARY « 




.WAIT 

• 1 

ICHECK FOR LISTING SPECIFICATION 


8C9 

NOLISTING 

INO LISTING DESIRED 

N0LISTIN5I 




.WAIT 

• 3 

ICHECK FOR INPUT FILE OPEN 


BCS 

ERROR 

INO INPUT FILE 

ERROR 1 

.EXIT 



OEXTI 

.RAD50 

/MAC/ 



, RAO50 

/OBJ/ 



.RAD50 

/L3T/ 



.WORD 

0 


DSPACE* 

• 




.END 

START 



.WRITE/.WRITC/.WRITW 


9.4.47 .WRITE/. WRITC/.WRITW 

Note that in the case of .WRITE and .WRITC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET). 

.WRITE 

The .WRITE request transfers a specified number of words from memory 
to the specified channel. Control returns to the user program 
immediately after the request is queued. 
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Macro Calls .WRITE .area, .chan, .buff, .went, .blk 

where: .buff is the address of the memory buffer to be 

used for output. 

.went is the number of words to be written. 

.blk is the number of the block to be written. 


Request Formats 


RO 4 .area: 


TT 


11 .chan 


.blk 


.buff 


.went 


Notes s 

See the note following .WRITW. 
Errors: 


Code Explanation 

0 Attempted to write past end-of-file. 

1 Hardware error. 

2 Channel was not opened. 


Example s 

Refer to the examples following .WRITW. 


.WRITC 

The .WRITC request transfers a specified number of words from memory 
to a specified channel. Control returns to the user program 
immediately after the request is queued. Execution of the user 
program continues until the .WRITC is complete, then control passes to 
the routine specified in the request. When an RTS PC is encountered 
in the routine, control returns to the user program. 


Macro Calls 

.WRITC 

.area, .chan, .buff, .went, .ertn, .blk 



where: 

.buff 

is the address of the memory buffer 
used for output. 

to 

be 


.went 

is the number of words to be written. 




.ertn 

is the address of the completion routine 

to 



be entered (see Section 9.2.8). 




.blk 

is the number relative to the start 

of 

the 


file, not block 0 of the device. The monitor 
translates the block supplied into an 
absolute device block number. The user 
program normally updates .blk before it is 
used again. 
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Request Format: 


RO 4 .area: 


11 |.chan 

TBTk - 

TBuTI- 


.went 

.ertn 


When entering a .WRITC completion function the following are true: 


1. RO contains the channel status word for the operation. If 
bit 0 of RO is set, a hardware error occurred during the 
transfer. The data may not be reliable. 

2. Rl contains the octal channel number of the operation. This 
is useful when the same completion function is to be used for 
several different transfers. 


Notes: 

See the note following .WRITW. 

Errors: 

Code Explanation 

0 End-of-file on output. Tried to write outside limits 

of file. 

1 Hardware error occurred. 

2 Specified channel is not open. 

Example: 

Refer to the examples following .WRITW. 


.WRITW 


The .WRITW request transfers a specified number of words from memory 
to the specified channel. Control returns to the user proqram when 
the .WRITW is complete. 


Macro Call: 
where: 


.WRITW 

.area, chan, .buff, .went, .blk 


.buff 

is the address of the buffer to be used 

for 


output. 


.went 

is the number of words to be written. 

The 


number must be positive. 


.blk 

is the number of the block to be written. 
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Request Format 


RO ^ .area: 



Note: 

Upon return from any WRITE programmed request, RO will contain no 
information if the write is to a sequential-access device (for example, 
magtape). If the write is to a random-access device (disk, DECtape), 
RO contains the number of words that will be written (.WRITE or .WRITC) 
or have been written (.WRITW). If a request is made to write past the 
end-of-file on a random-access device, the word count is shortened and 
an error is returned. Note that the write will be done and a completion 
routine, if specified, will be entered, unless the request cannot be 
partially filled (shortened word count = 0). 


Errors: 


Code Explanation 

0 Attempted to write past EOF. 

1 Hardware error. 

2 Channel was not opened. 

Examples: 

The following routine illustrates the differences between the three 
types of .READ/.WRITE requests and is coded in three ways, each using 
a different mode of monitor I/O. The routine itself is a simple 
program to duplicate a paper tape. 


In the first example, .READW and .WRITW are used. The I/O is 
completely synchronous, with each request retaining control until the 
buffer is filled (or emptied). 

,MC*U ,.V2..,.REGDEF,.FETCH,.READW,.WRITW 
. MCALL .ENTER..LOOKUP,.PRINT..EXIT,.CLOSE,.WAIT 
..V2,. 

.REGDEF 


ERRW0«52 


STARTl .FETCH iHSPACE,APRNAME 
BCS FERR 

MOV R0.R2 

.FETCH R2,#PPNAM£ 

BCS FERR 

MOV RAREA.RS 

CLP R« 

MOV #1,R3 

.ENTER RS,R4,tPPNAME 
BCS ENERR 

.LOOKUP R5,R3,KPRNAME 
BCS LKERR 

CIR R1 

100PI .READW RS,R3,#BUFF,#256 
BCS RDERR 

.WRITW R5,R«,#BUFF,#256 


J GET PR HANDLER 

I PR NOT AVAILABLE 

»R0 HAS NEXT FREE LOCATION 

f GE T PP HANDLER 

I NOT AVAILABLE 

»EMT ARGUMENT AREA 

IRA IS OUTPUT CHANNEL! 0 

IRS IS INPUT CHANNEL 11 

I ENTER THE FILE 

ISOME ERROR IN ENTER 

I LOOKUP FILE ON CHANNEL 1 

I ERROR IN LOOKUP 

IUSE R1 AS BLOCK NUMBER 

., R1 I RE AD ONE BLOCK 

,,Rl IWRITE THAT BLOCK 
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BCS 

UTERR 




INC 

Ri 


1 BUMP BLOCK, NOTE 1 THIS IS 

INOT NECESSARY FOR NON-FILE 
IDEVICES IN GENERAL. IT IS 

1 USED HfcRE AS AN EXAMPLE OF 

1A general TECHNIQUE. 


SR 

LOOP 


I KEEP GOING 


TSTB 

ERRWD 


1ERROR. IS IT EOF? 


BE Q 

IB 


1 YES 


.PRINT 
• EXIT 

#RDM8G 


I NO, HARO READ ERROR 

lit 

.CLOSE 

R3 


ICLOSE INPUT AND OUTPUT 


.CLOSE 
• EXIT 

HU 


1 AND EXIT, 

WTERRI 

.PRINT 

.EXIT 

tWTKSG 



PRNAMEI 

.RAD50 

/PR / 


INOTE THAT PR NEEDS NO FILE NAME 


.WORD 

0 


fFILE NAME NEED ONLY BE 0, 

PPNAMEI 

.RAD50 

/PP / 




. WORO 

0 


1 ERROR ACTIONS 60 HERE. IT IS 

FfcRRl 

.PRINT 

PFNSG 



.EXIT 



^generally undesirable TO 

ENERRl 

.PRINT 

AEMSG 


1 EXECUTE A HALT OR RESET 


.EXIT 



INSTRUCTION ON ERROR. 

LKERRJ 

.PRINT 
• EXIT 

ALMSG 



FM8GI 

.ASCII 

/NO DEVICE?/ 


EMSGI 

. ASCIZ 

/ENTRY 

ERROR?/ 


LM8GI 

.ASCII 

/LOOKUP ERROR?/ 


RDMSGl 

.ASCII 

/REAO 

ERROR?/ 


WTMSGl 

.ASCII 

.EVEN 

/WRITE 

ERROR?/ 


ARE A 1 

,BLM 

10 



BUFFI 

.BLKW 

256. 



HSPACE« 

• 





.END 

START 



The same 

routine 

can be 

coded using .READ and .WRITE as follows. 


.WAIT request is used to determine if the buffer is full or empty 
prior to its use. 


.MCALL 

,.V2..,.REGDEF, 

.FETCH,.REAO,.WRITE 

.mcall 

.ENTER,.LOOKUP, 

•PRINT,.EXIT,.CLOSE,.WAIT 

»,V£,, 



.RE60EF 



ERRwO>52 



START 1 .FETCH 

•hSPACE,*PRNAME 

|GET PR HANDLER 

BCS 

FERR 

|PR NOT AVAILABLE 

MOV 

R0,R2 

IR0 HAS NEXT FREE LOCATION 

.FETCH 

R2,KPPNAME 

1 GET PP HANOLER 

BCS 

FERR 

INOT AVAILABLE 

MOV 

FARE A,R5 

IEMT ARGUMENT AREA 

CLR 

RA 

IRA IS OUTPUT CHANNELI 0 

MOV 

*1,R3 

|H3 IS INPUT CHANNEL 11 

.Enter 

R5,RA,FPPNAME 

1 ENTER THE FILE 
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LOOP* 


RDERRl 


IOERR* 

PRNAME < 

PPNAMEI 

FERR* 

ENERRI 

LKERR* 

FM8G I 

EM8GI 

LMSGI 

I0MSGI 

WTMSGl 

AREA* 

BUFFI 

HSPACE*. 


BCS ENERR /SOME ERROR IN ENTER 

• LOOKUP R5,R3, APRNAME /LOOKUP FILE ON CHANNEL, l 
BCS LKERR JERROR IN LOOKUP 

CLR R1 /USE R1 AS BLOCK NUMBER 

.READ R5,R3,#BUFF,#25b.,Rl >READ A BUFFER 
BCS ROERR 

.WRIT R3 /WAIT FOR BUFFER 

BCS IOERR I ERROR HERE IS HARO ERROR 

.WRITE R5.R4,#BUFF,*25b.,Rl /WRITE TTHE BUFFER 

/I/O ERROR 

I KEEP GOING 
I ERROR, IS IT EOF? 

I NO f HARO ERROR 
I CLOSE INPUT AND OUTPUT 

IANU EXIT, 

I NOi HARO READ ERROR 

/note that pr needs no file name 

I FILE NAME NEED ONLY BE 0. 


I ERROR ACTIONS GO HERE. IT IS 
I GENERALLY UNDESIRABLE TO 
/EXECUTE A HALT OR RESET 
I INSTRUCTION ON ERROR, 

.EXIT 

,ASCIZ /NO DEVICE?/ 

.ASCIZ /ENTRY ERROR?/ 

.ASCIZ /LOOKUP ERROR?/ 

.ASCIZ "I/O ERROR?" 

.ASCIZ /WRITE ERROR?/ 

.EVEN 

.BLKW 10 
.BLKW 25b, 

.END START 


BCS 

IOERR 

INC 

Ri 

8R 

LOOP 

TST6 

ERRWO 

BNE 

IOERR 

.CLOSE 

R3 

.CLOSE 

R# 

.exit 


.PRINT 

AIOMSG 

.EXIT 


.RAO50 

/PR / 

• WORD 

0 

,R*050 

/PP / 

.WORO 

0 

.PRINT 

PFMSG 

.EXIT 


.PRINT 

«EMSG 

.EXIT 


.PRINT 

OLMSG 


.READ and .WRITE are also often used for double-buffered I/O. The 
basic double-buffering algorithm for input is: 

Explanation 


LOOP: 


READ 

BUFFER 1 

Fill BUFFER 1 


WAIT 

BUFFER 1 

Wait for BUFFER 1 to fill 


READ 

BUFFER 2 

Start filling BUFFER 2 


USE 

BUFFER 1 

Process BUFFER 1 while BUFFER 

2 

WAIT 

BUFFER 2 

Wait for BUFFER 2 to fill 


READ 

BUFFER 1 

Start filling BUFFER 1 


USE 

BUFFER 2 

Process BUFFER 2 while BUFFER 

1 

BR 

LOOP 




fills 

fills 
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Correspondingly, the basic double-buffering algorithm for output is: 

Explanation 


FILL BUFFER 1 
LOOP: WRITE BUFFER 1 

FILL BUFFER 2 

WAIT BUFFER 1 
WRITE BUFFER 2 
FILL BUFFER 1 

WAIT BUFFER 2 
BR LOOP 


Prepare BUFFER 1 for output 
Start emptying BUFFER 1 
Fill BUFFER 2 while BUFFER 1 
empties 

Wait for BUFFER 1 to empty 
Start emptying BUFFER 2 
Fill BUFFER 1 while BUFFER 2 
empties 

Wait for BUFFER 2 to empty 


The previous example program can be coded using completion routines 
via .READC and .WRITC as follows. Once the initial read is performed, 
the remainder of the I/O is performed by the completion routines. 

’.MCaLL ..V8..,.REGDFF,.FETCH,,REAOC,.WRITC 

■.mcall .ENTER,.LOOKUP,.print,.exit,.close..WATT 
• • V 2., 

.regoef 


ERRBYTrS* 

STARTl 

.PITCH 

BC* 

MOV 

'.fetch 

F LNK! 

PC* 

MOV 

cl* 

MOV 

‘.ENTER 

PCS 

’.LOOKUP 

§cs 

CL« 

LOOP 1 

Cl" 

.REaoc 

PCS 

131 

TST 

BEG 

RMl 

fof: 

.close 

.close 

.EXIT 

•enafl 

LS» 

RDCOMp j 

pqR 

PC* 

.WRITC 

BCC 

RWFRRl 

MOV 

?$! 

RT« 

WRCOMp! 

POP 

PCS 

INC 

'.reaoc 

pcc 

TST« 


#HSP*CE,#P»NAMF 

fink 

R0.R? 

R2,#RRNAME 

ferr 

#ARE*,R5 

ra 

#1,R* 

R5,R«,*ppnamf 

ENPRR 

R5,R5,*PRNAMF 

LKFRR 

Rt 

oflg 

RS.RS.PBUFF.oase 

FOP 

OPiG 

IS 

TOFRR 
Ra 


IGFT pR HANDLER 

IPR NOT AV»ILA*LF 

|R0 has NEVT FREF LOCATION 

igft pp hanoler 

INOT AVAILABLE 
IEHT ARGUMENT AREA 
IRA IS OUTPUT CHANNEL! 0 
IRS IS INpi'iT CHANNFL ! t 
I ENTER THE FILE 
ISOME ERROR IN ENTFR 
I LOOKUP fjiE ON CHANNEL 1 
IERROR IN LOOKUP 
JUSE R1 *S BLOCK NUMBER 
»Cl.EAR OONF/ERROR FLAG 
.,PROCOMP,Ri !REAQ ONE BLOCK 
INO ERROR WILL HAPPEN HERE 

i done flag sett 

»N0, WAIT POR TT TO RE SFT. 

IYFS» RUT HARO ERROR OCCURRED 
ICLOSE INPUT AND OUTPUT CHANNELS 

I ALL DONE 


017) IIP PIT 0 SET 

»WPRR I AN ERROR OCCURRED. 

#ABEA,#0,#RUFF,#?5*..#WRCOMP,BLKN .WRITE THAT BLOCK 

?$ .ERROR HERF TS HARDWARE 

*.1 , Opl.G I FLAG THE ERROR 

PC 

R0 

PWFHR .HARDWARE ERROR ( 

RLKN IBUMP BLOCK NUMBER. 

«APEA,*1,PRUEF,#?5R.,«R0C0MP,BLKN 

3$ INO ERROR 

EROSVT IEOFT 
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RNE 

BInESB 


INC 

OFI 6 

3SI 

RTS 

PC 

.0*A«L 

1 S» 


EERRl 

MOV 

RFMSO,R0 


RR 

typit 

ENFRBj 

MOV 

#EMSG,R0 


RR 

typit 

TOERRl 

MOV 

#idm$g,r« 


RR 

typit 

LKERRl 

MOV 

#L m SG,R0 

TYPITJ 

.PRINT 


.nlist 

,E*IT 

BEX 


fmsgi 

.ASCIZ 

/NH DEVICE?/ 

EMSGI 

.asctz 

/ENTRY ERROR?/ 

LM8GI 

.ASCIZ 

/LOOKUP ERROR? 

lOMSfti 

.ASCTZ 

"I/O error?" 

.LIST REV 


.EVEN 

0ELG1 

.WORD 

0 

PRNAMEi 

.RAOR0 

/PR / 


.WORD 

01 

PpNAMEI 

.RAOR0 

/PP / 


.WORD 

0 

R L K N1 

'. WORD 

0 

AREAI 

.BlKW 

10 

BUFFI 

, blkw 

?5A. 

HSPACE* 

• 



.END 

start 


• NO, HARO ERROR 
ISAY WE'RE DONE 


I ERROR ACTIONS GO MERE. TT I» 
IGFNERALLY undesirable TO 

•EXECUTE A HALT OB RESET 

instruction on error. 


INOTE that PR NEEDS no file name 
IETLE name NEED ONLY be 0, 


•BLOCK NUMBER 


The following example incorporates the .LOOKUP, .READW, and .CLOSE 
requests. The program opens the file RT11.MAC which is on the system 
device, SYs, for input on channel 0. The first block is read and the 
tile is then closed. 


.MCALL ,.V2,,, .REGDEF,.CLOSE,.LOOKUP 
.MCALL .PRINT,.EXIT,,REAOK,.FETCH 

..V2.. 

.REGDEF 


START! 

MOV 

PLIST,R5 

IEMT ARGUMENT LIST POINTER 


CLR 

R4 

•BLOCK NUMBER 


CLR 

R J 

•CHANNEL 4 


.FETCH 

acc 

•CORAOD,PFPTR 

IS 

•FETCH OEVICE HANDLER 

IS! 

MOV 

EEETMSG #R0 

•FETCH ERROR 

.PRIM 

.exit 


•PRINT ERROR MESSAGE 

2SI 

.LOOKUP 

acc 

R5,R3,PFPTR 

34 

•lookup file on channel 0 


MOV 

SR 

•LKMSG.R0 

ts 

•PRINT FAILURE MES8AGE 

SSI 

.READW 

acc 

R5,R3,PBUFF,#254,,Rft I REA ONE BLOCK 

44 


MOV 

BR 

4NOMSG.R0 

IS 

•READ ERROR 

4SI 

.CLOSE 

.EXIT 

R3 

•CLOSE THE CHANNEL 

LIST! 

.BLEW 

5 

•LIST FOR EMT CALLS 

FPTHI. 

.HAD50 

/SY RT1i MAC/ 

•RAO50 OF EIEL NAME,DEVICE 

FETMSGI 

.ASCIZ 

/FETCH FAILED/ 

•ASCII MESSAGES 

LKMSGl 

.ASCIZ 

/LOOKUP FAILED/ 
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RDMSGl 

.ASCII 

/READ FAILED/ 


CQRADOJ 

.EVEN 
, BLKW 

20063 

JSRACE FOR LARGEST HANDLERS 

BUFF*. 





.END 

START 



9.5 CONVERTING VERSION 1 MACRO CALLS TO VERSION 2 


As mentioned in the introduction of this chapter, 
supports a slightly modified format for system 
Version 1. This section details the conversion 
Version 1 format to Version 2. 


RT-11 Version 2 
macro calls than 
process from the 


9.5.1 Macro Calls Requiring No Conversion 
Version 1 macro calls which need no conversion are: 


CSIGN 

.RCTLO 

CSISPC 

.RELEAS 

DATE 

.SETTOP* 

DSTATUS 

.SRESET 

EXIT 

.TTINR** 

FETCH 

.TTOUTR 

HRESET 

.TTYIN 

.LOCK 

.TTYOUT 

.PRINT 

.UNLOCK 

,QSET 



♦Provided location 50 is examined for the maximum value. 
♦♦Except in F/B System. 


9.5.2 Macro Calls Which May Be Converted 


The following Version 1 macro calls may be converted: 


.CLOSE 

.DELETE 

.ENTER 

.LOOKUP 

.READ 


.RENAME 

.REOPEN 

.SAVESTATUS 

.WAIT 

.WRITE 


The general format of the Vl macro is: 

.PRGREQ .chan, .argl .arg2,...argn 

In this form, .chan is an integer between 0 and 17 (inclusive), and 
is not a general assembler argument. The channel number is assembled 
into the EMT instruction itself. The arguments argl-argn are always 
pushed either into R0 or on the stack. 

The V2 equivalent of the above call is: 

.PRGREQ .area, .chan, .argl,....argn 
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In the V2 call, the .chan argument cam be any legal assembler 
argument; it need not be in the range 0 to 17 (octal), but should be 
in the range 0-377 (octal), .area points to a memory list where the 
arguments argl...argn will go. 

As an example, consider a .READ request in both forms: 

VI: .READ 5,#BUFF,#256.,BLOCK 

V2: .READ #AREA,#5,#BUFF,#256.,BLOCK 


AREA: 


.WORD 0 ;CHANNEL/FUNCTION CODE HERE 

.WORD 0 ;BLOCK NUMBER HERE 

.WORD 0 ;BUFFER ADDRESS HERE 

.WORD 0 ;WORD COUNT HERE 

.WORD 0 ;A 1 GOES HERE. 


Thus, the difference in the calls is that xn Version 2 the channel 
number becomes a legal assembler argument and the .area argument has 
been added. 


Following is a complete list of the conversions necessary for each of 
the EMT calls. Both the Version 1 and Version 2 formats are given. 
Note that parameters inside [] are optional parameters. Refer to the 
appropriate section in this chapter for more details of each request. 

Version Programmed Request 


VI: .DELETE .chan,.dblk 

V2: .DELETE .area,.chan,.dblk,(.count] 


VI: .LOOKUP .chan,.dblk 

V2: .LOOKUP .area, .chan,.dblk,[.count] 

VI: .ENTER .chan,.dblk,[.length] 

V2: .ENTER .area,.chan,.dblk,[.length],(.count] 

VI: .RENAME .chan,.dblk 

V2: .RENAME .area,.chan,.dblk 


VI: .SAVESTAT ,chan,.cblk 

V2: .SAVESTAT .area,.chan,.cblk 

VI: .REOPEN .chan,.cblk 

V2: .REOPEN .area,.chan,.cblk 

VI: .CLOSE .chan 

V2: .CLOSE .chan 

VI: .READ/.READW .chan,.buff,.went,.blk 

V2: .READ/.READW .area,.chan,.buff,.went,.blk 

VI: .READC .chan,.buff,.went,.ertn,.blk 

V2: .READC .area,.chan,.buff,.went,.ertn,.blk 

VI: . WRITE/.WRITW .chan,.buff,.went,.blk 

V2: .WRITE/.WRITW .area,.chan,.buff,.went,.blk 
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VI: 
V2: 


.WRITC .chan,.buff,.went,.ertn,.blk 
.WRITC .area,.chan,.buff,.went,.ertn,.blk 


VI: 

V2: 


.WAIT .chan 
.WAIT .chan 


Important features to keep in mind for Version 2 calls are: 

1. Version 2 calls require the .area argument, which points to 
the area where the other arguments will be. 

2. Enough memory space must be allocated to hold all the 
required arguments. 

3. .chan must be any legal assembler argument, not just an 
integer between 0-17 (octal). 

4. Blank fields are permitted in the Version 2 calls. Any field 
not specified (left blank) is left alone in the argument 
block. 
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CHAPTER 10 


EXPAND UTILITY PROGRAM 


EXPAND is an RT—11 system program which processes the macro references 
in a macro assembly language source file. EXPAND accepts a subset of 
the complete macro language and/ using the system library file 
SYSMAC.8K, produces an output file in which all legal macro references 
are expanded into macro-free source code. EXPAND is normally used 
with ASEMBL, the RT-11 assembler designed for minimum memory 
configurations (refer to Chapter 11). 


10.1 LANGUAGE 


EXPAND simply copies its input files to its output file unless it 
encounters any of the following directives (see Chapter 5 for more 
information about these directives): 

1. .MCALL Directs EXPAND to search the file 

SYsSYSMAC.SML to find the macro names listed 
in the .MCALL directive. If the macro names 
are found, EXPAND stores their definitions in 
its internal tables. 


2. .MACRO 


3. .name 


4. .ENDM 


Directs EXPAND to copy a macro definition 
from the user's input file into the internal 
tables. 

If .name is the name of a macro defined in 
either a .MCALL or .MACRO directive, then 
.name is expanded according to the definition 
stored for it in the EXPAND internal tables. 

If encountered while storing a macro 
definition, the .ENDM directive terminates 
the definition. It is not recognized outside 
macro definitions. 


10.2 RESTRICTIONS 

Unlike the full macro assembler (MACRO), EXPAND only expands macros 
that observe the following restrictions: 
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1 . 


2 . 


The following directives may 

.ERROR 

.NARG 

.IF DIF 

.NCHR 

.IF IDN 

.NTYPE 

• IRP 

.PRINT 

• IRPC 

.REPT 

.MEXIT 


Macros cannot be 

nested. 


Recursive macros that call 


error message, 


3. Macros cannot be redefined. Once a name has been used for a 
macro name, it cannot be used again in the program for a 
macro or symbol name. 

4. Macro names must begin with a dot (•)• If the dot is missing, 
an error message is printed. 

5. Dummy argument names must begin with a dot (•)• Such names 
cannot be used as dummy argument names in the macro but can 
be used for other purposes outside of the macro. 

6. The backslash operator is not available. 

7. Automatically created symbols are not available. 

8. No more than 30 arguments may be used in any MACRO directive. 


10.3 CALLING AND USING EXPAND 
To run EXPAND, type: 

R EXPAND 

in response to the dot printed by the Keyboard Monitor. EXPAND 
responds with an asterisk indicating that it is ready to accept a 
command string. A command string must be of the following form: 

*ofile=ifilel,ifile2,...,ifil©6 

ifile2 through ifile6 are optional. Each file specification follows 
the general RT-11 command string syntax (dev:filnam.ext). The default 
value for each file specification is noted below: 


I/O File 

Dev 

Ext 


— 

ofile 

DK 

PAL 

ifilel,..., 

device used 

MAC 

ifile6 

for last source 
file specified 
or DK 



Type CTRL C to halt EXPAND and return control to the monitor. To 
restart EXPAND, type R EXPAND or the REENTER command in response to 
the monitor's dot. 
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oSt C fiie S unfci? nt j» allY thS ®? ecif f ed i] ?P ut to the specified 

, ^ e un ^ 1 ^ a macro directive is encountered. EXPAND then 

2!i"sr h f i s oti y e , to ? oo r ent b * « .eS!X, “ 

it will not be seen later by the assembler (usually ASEMBL). 

(SYS^C d 8^ Ct for i ! h ‘ MCALL ' E * P ™ D sea *ches the system library file 
(SYSMAC.SR) for the requested macro definitions. The requested 

ar % thea included in the user’s program in the order in 
which they are found in the library. 

For the .MACRO directive, EXPAND reads each line followinq the 
directive up to the next .ENDM directive. Each line is stored in the 

file^sn d th X t i<: ^t n • table and then Ranged to a comment in the output 
Surrmrp^f lt 1S n0t P rocessed later by the assembler. Also, any 
of a "* ac f° argument name within the definition is flagged 
internally so that it can be replaced by the real argument value 
whenever the macro is later referenced. vaiue 

Hi m intLn^ fe t^? eS ' k XP ^ N ° ^° Cates the stored ra ac ro definition in 
s “ tables, binds the actual argument values to the argument 
names, and changes the macro reference to a comment line. EXPAND then 
begins copying the stored definition to the output file. Whenever a 

hv C ^ argUment ^ iS encounte red in the definition, it is replaced 
by the corresponding actual argument value. p 

Examples: 

The following are examples of input and corresponding EXPAND output. 


INPUT 


OUTPUT 


Rl»X1 

9P»Xt» 

PC«XT 

.MACRO 

JS* RC 

,ENqm 

.mcall 


.CAUL .9UPR 
, 9UPR 

.LOCKUP,.READ 


..V?.. 


I RT-ll MACRO EXPAND V02-02 

Ri"XI 

9P»X*> 

PC»XT 

t .MACRO .CAI.L . 9UPR 

t J$R PC..9URH 

I ,EN0M 

» .MCALL .lookup,.read,..V?.. 

». MACRO , ,V2,, 
t • • » V2»l 
).enom 


(.MACRO .LOOKUP 
».IP dp ...VI 

1.IF NR .CHAN 

.AREA, 

.CHAN,.DEVPLK, 

1 

t ,EN0C 

MOV 

.CHAN,X0 

I 

».TFP 

».!F NP .AREA 

EMT 

*O«20*.AREA» 

» 

MOV 

.AREA,X0 

1 

1.ENOC 

( , IF NP .CHAN 

Move 


» 

».ENOC 

MOVB 

.CHAN,(01 
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• 0 


V2 


0 0 


ST AC* I 

ARFAI 

RUFRI 

INBLKl 

START! 

Al 

II 


,C»£CT MAIN 

.glorl sort 

.BLKW 100 
.BLKW 10 
.BLKW 100 

,blkw r 
MOV #stack,sp 

M0 V Rli-(S B ) 
,C*LL SORT 


.LOOKUP #INBLK,0 


I.TF NR , 

.OSVRLK 


1 


MOV 

I .FNOC 



I.IF NR 

.SPF 


1 


MOV 

1 .IFF 



1 


et» 

1.FNOC 



1 


FMT 

I.FNOC 



1.ENOM 



i .macro 

,RKAO 

.A»EA 

1.TF OF 

...VI 


1,IF NR 

.WCNT 


1 


MQV 

».ENOC 



» 


MOV 

1 


MOV 

1 


MQV 

1 


FMT 

I.IFF 



1,TF NR 

.AREA 


1 


MOV 

1 


MO VB 

I.FNOC 



1,IF NR 

.chan 


1 


MQVB 

I.FNOC 



I.TF NR 

,blk 


I 


MOV 

1 .FNOC 



I.TF NR 

.BUFF 


1 


MQV 

I.FNOC 



1.IF NR 

.WCNT 


1 


MOV 

1.FNOC 



» 


MOV 

1 


FMT 

I.FNOC 



f,FNOM 



1 

..V2.. 



,OPVBLK,?.(0) 

, 3PF»4.(B) 

«, f05 

*057*5 

CHAN,.BUFF,.WCNT,,BLK 

,WCNT,X0 

.BUFF,• (B • 7 
.CHAN,.(*>,! 

*O«200<-.*RF4» 


.AREA.X0 

# 8 ., 1 (») 

.CHAN, (0 ) 

.BLK, 2 .(B) 

.BUFF,a.(01 

,WCNT,fe,(01 

#1,8.(B) 
*0575 


...V?«1 

.CSECT MAIN 
.GLORL SORT 

STACKI 

.BLKW 100 

ARFAI 

.BLKW 10 

RUFRI 

.BLKW 100 

INRLKI 

.BLKW 5 

START! 

MOV #stack,sp 

Al 

MOV Rl,-(SF) 

Rtf 

,C*LL SORT 

JSR PC i SORT 


,L°OKUP «INBLK»0 


IF OF 

...VI 



IF N0 

0 

MOV 

0,50 

ENOC 


FMT 

*0«2B+*INBIK* 

IFF 
i IF NB 

iTNBLK 
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et« Pi IBLOCK NUMBER 

.REAR #ABEA,#0,#BUPR,#356.,R1 




MOV 

•INBLK.X0 



MOVB 

#1.1(0) 

.ENDC 
.IF NB 

0 

MOVB 

0, (0) 

.ENDC 
.IF NB 


MOV 

.2.(0) 

.ENDC 

.IF NB 


MOV 

,4.(0) 

.IFF 


CLP 

4.(0) 

.ENDC 


FMT 

*0575 

.ENDC 

clR pi 


»BLOCK NUMBER 

1 

.rear 

#APEA,#0, 

#BUFR.#256,.R1 

.IF RF 

...VI 



.IF NB 

0956, 

MOV 

#256.,X0 

.ENDC 


MOV 

#l.-(6.) 



MOV 

#BUFP,-(6.) 



MOV 

#0,-(6.) 



FMT 

*O<200A#AREA# 

.IFF 
.IF NB 

0arEa 

MOV 

0APE4.X0 



MOVB 

#8.,1(0) 

.ENDC 
.IF NB 

.ENDC 

.IF NB 

#01 

MOVB 

#0.(0) 

R1 

MOV 

PI,2.(0) 


.ENDC 
.IF NB 

0BUFR 

MOV 

«BUFP,4.(0) 

.ENDC 
.IF NB 

#356. 

MOV 

#256,,6,(0) 

.ENDC 


MOV 

•1.6.(0) 



EMT 

*0175 

.ENDC 





halt 

.eno start 


halt 

.end start 
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10.4 EXPAND ERROR MESSAGES 

The following messages are caused by fatal errors detected by EXPAND. 
They print on the console terminal and cause EXPAND to restart: 


Message 

Explanation 

?BAD SWITCH? 

An unrecognized command string 

switch was specified. 

?INPUT ERROR? 

Hardware error in reading an input 
file. 

?INSUFFICIENT CORE? 

Not enough memory to store macro 
definitions. 

?MISSING END IN MACRO? 

End of input was encountered while 
storing a macro definition; 
probably missing an .ENDM. 

?NO INPUT FILE? 

There must be at least one input 
file. 

?OUTPUT DEVICE FULL? 

No room to continue writing output; 
try to compress the device with 
PIP. 

?WRONG NUMBER OF OUTPUT FILES? 

There must be exactly one output 
file. 


The following errors are non-fatal but indicate that something is 
wrong in the input file(s). These errors appear in the output file as 
a line in the following form: 

?*** ERROR *** message 

After each run of EXPAND, the total number of non-fatal errors is 
printed on the console terminal. 


Message 

Explanation 

BAD MACRO ARG 

The macro argument is not formatted 
correctly. 

LINE TOO LONG 

A line has become longer than 132 
characters. 

MACRO ALREADY DEFINED 

A macro was defined more than once. 

MACRO(S) NOT FOUND 

Macros listed in an •MCALL 
statement were not found in 
SYSMAC.8K (make sure SYSMAC.8K is 
present on system). 

MISSING COMMA IN MACRO ARG 

Found spaces or tabs within a macro 
argument when a comma was expected; 
try using brackets around the argu¬ 
ments, e.g., <arg with spaces>. 


January 1976 
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MISSING DOT 

A macro name or argument name does 
not begin with a dot. 

NAME DOESN'T MATCH 

Optional name given in .ENDM 
directive does not match name given 
in corresponding .MACRO directive. 

NESTED MACROS 

A macro is being defined or invoked 
within another macro. 

NO NAME 

A macro definition has no name. 

SYNTAX 

A macro directive is not 

constructed correctly. 

TOO MANY ARGS 

A macro directive has more than 30 
arguments• 
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CHAPTER 11 

ASEMBL, THE 8K ASSEMBLER 


ASEJffiL is designed for use on an RT-11 system with minimum 
space (or larger systems where system table space is critical) 
a subset of the RT-11 MACRO assembler described in cLpter S. 
has the same features as MACRO with the following exceptions: 


memory 
and is 
ASEMBL 


1 . 


MACRO directives (.MACRO, .MCALL, .ENDM, .IRP, etc.) are 
recognized 


not 


2. DATE is not printed in listings 

3. wide line-printer output is not available 

4. There is no lower-case mode 

5. There is no enable/disable punch directive 

6. There are no floating point directives 

7. There are no local symbols or local symbol blocks 

8. CREF is not available 


Sr^b'ef !„"Saptfr a w? S “ e SUPP<>rted ^ ““ EXMND (as 


11.1 CALLING AND USING ASEMBL 


ASEMBL is loaded in response to the dot printed by the 
Monitor with the RT-11 monitor R Command as follows: 


Keyboard 


R ASEMBL 



*object,listing=sourcel,...,source6 
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where: 


object is a binary object file output by ASEMBL. 

listing is the assembly listing file containing the 
assembly listing and symbol table. 


sourcel,•••,source6 

are the ASCII source 
source program(s)• 
is allowed. 


files containing the ASEMBL 
A maximum of six source files 


A null specification in any of the file Jgf* 

associated input or output file is not desired. ASEMBL file 
specifications follow the standard RT-11 convention (dev:fllnam.ext). 
The default value for each file specification is noted below: 


I/O File 

object 

listing 

sourcel,•••, 
sourcen 


Dev 

Ext 


” 

DK 

.OBJ 

device used 

for object output 

.LST 

device used for 
last source 
file specified 
or DK 

.PAL 


Type CTRL C to halt ASEMBL and return control to the monitor. To 
restart ASEMBL, type R ASEMBL or the REENTER command in response to 
the monitor 1 s dot. 


Table 11-1 lists the RT-11 macro directives which are not available in 
ASEMBL. 


Table 11-1 

Directives not Available in ASEMBL 


Directive 

Explanation 

.MACRO ''l 

Macros cannot be defined in ASEMBL. 

.ENDM V 


.MEXIT ( 


.MCALL J 


.NCHR 

The number of characters in an argument cannot be 


obtained with a macro. 

.NARG 

The number of arguments in a macro cannot be 


obtained with a macro. 

\ (backslash) 

Symbols used as macro arguments cannot be passed 


as a numeric string. 


(continued on next page) 
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Table 11-1 (Cont.) 
Directives not Available in ASEMBL 


Directive 

Explanation 

.ERROR 

Messages cannot be flagged with a P error code 
output as part of the assembly listing. Comment 
lines can be used to replace .ERROR. 

.IF IDN ^ 

.IF DIF J 

Strings cannot be compared. 

• IRP \ 

. IRPC J 


Indefinite repeat blocks cannot be created. 

•NTYPE 

A macro cannot be modified based on the addressing 
mode of an argument. 

.PRINT 

Messages cannot be output as part of the assembly 
listing. Comment lines can be used to replace 
.PRINT. 

.REPT 

A block of code cannot be duplicated a number of 
times in-line with other source code using a 
directive. 

.LIST ME ^ 

•NLIST ME 
.LIST MEB 
.NLIST MEB 
.LIST MD 
.NLIST MD 
.LIST MC 
.NLIST MC > 

> 

These directives have no effect. 

.LIST TTM 1 

.NLIST TTM > 


Terminal mode is standard and cannot be changed. 

.ENABL LC \ 

.DSABL LC J 

All lower case ASCII input is converted to 
upper case. 

.ENABL LSB 1 
.DSABL LSB / 

Local symbols and local symbol blocks are not 
available in ASEMBL. 

.ENABLE PNC 
.DSABL PNC J 

Binary output is always enabled. 

.ENABL FPT 
.DSABL FPT 
. FLT2 
. FLT4 

} 

Floating point directives are not available. 


Example: 

This example uses the output produced by the EXPAND program as input 
to ASEMBL, The assembly listing follows. 
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.MAIN. RT-11 MACHO Vaoa-1* 


FA6E 1 


3 

000001 


Rl-Xl 



4 

000006 


SPaU 



5 

000007 


PC«XT 



6 


I 

'.MACRO 

•CALL . 

SUBR 

7 


t 

J3R FCi 

.9UAR 


8 


f 

'.ENOM 



9 


f 

’.Me all 

.LOOKUP 

».READ. . . V 2. , 

10 


1 .MACRO 

• • V 2 • . 



11 


J...V2-1 



12 


1 , FNOM 




13 


1 .MACRO 

'.LOOKUP 

• AREA # 

.CHAN,.0FVRIK,.I 

14 


I.TF 08 

;..vi 



15 


I.TF Ni 

.CHAN 



16 


1 


MOV 

, CHAN,70 

17 


I.FNOC 




18 


1 


FMT 

*O<20T-.AREA> 

19 


1 ,TFF 




20 


l.TF NR 

.AREA 



21 


1 


MOV 

.AREA,70 

22 


1 


MOVB 

#1,1(01 

23 


I.FNOC 




24 


l.TF N0 

.CHAN 



25 


1 


MOVB 

‘.CHAN, (01 

26 


I.FNOC 




27 


l.TF NR 

'.OFVRL* 



28 


1 


MOV 

.OFVRLF,2,(01 

29 


1.FNOC 




30 


l.TF NR 

'.8RF 



11 


1 


MOV 

,SRF,4.(0) 

32 


1 ,TFF 




33 


1 


CLR 

4 , f 01 

34 


».FNOC 




35 


1 


FMT 

*0875 

36 


I.FNOC 




37 


1,FN0M 




38 


1 .MACRO 

,RFAO 

.AREA, 

. chan,, buff, '.we 

39 


I.TF OF 

‘..'.VI 



40 


I.TF NR 

.WONT 



41 


1 


MOV 

.WONT,70 

42 


1.FNOC 




43 


1 


MOV 

#l,-(6.) 

44 


1 


MOV 

.BUFF,-(6,1 

45 


1 


MOV 

.CHAN,-(6,1 

46 


I 


FMT 

*O«200*.AREA* 

47 


1 , TFF 




48 


I.TF NR 

.AREA 



49 


1 


MOV 

.AREA,70 

50 


1 


MOVB 

#8*. ,1(0) 

51 


I.FNOC 




52 


I.TF NR 

'.CHAN 



53 


1 


MOVB 

'.CHAN, (01 

84 


1.FNOC 




55 


I.TF NR 

*.BLK 



56 


1 


MOV 

,BLK,2.(0) 

57 


1.FNOC 
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.MAIN. 

9T-11 MACRO V800-10 RASE 1* 


56 

».TF Ni '.BUFF 


59 

1 

MOV 

.61133,4,701 

60 

t.FNOC 



61 

I.TF Ni .WONT 


62 

9 

MOV 

‘.WCNT,6.701 

63 

9 .FNDC 



64 

9 

MOV 

• 1 . 8 .70) 

65 

9 

FMT 

*0375 

66 

l.fNOC 



67 

f ,*ndm 



66 

9 

••V2«• 


69 

000001 . . V 2 • 1 


70 

000000* 

'.C8ECT MAIN 


71 


’.slobl SORT 


72 0009)0 

8TACKI 

jBLKW 100 


73 00200 

arfai 

.BLKW 10 


74 00220 

iU3Rt 

'.BLKW 100 


75 00420 

IN3LF» 

'.BLKW 3 


76 00432 

012706 STAR7| 

MOV #STACK,S3 



000000* 



77 00436 

010146 At 

MOV Rl,.f8PJ 


76 00440 

i 1 f 

.CALL 8QRT 


79 00440 

004767 

.fSR PC.SORT 



000000G 



60 

1 

.LOOKUP 4INBLK 

• 0 

61 

.10 of 

...VI 


62 

.13 NB 

0 


83 


MOV 

0,30 

64 

.ENDC 



65 


EMT 

*O«20+*INBLK> 

A 6 

.133 



87 

.13 NB 

otnblk 


66 00444 

012700 

MOV 

*INBLK,*0 


000420* 



89 00430 

112760 

MOVB 

#1,1701 


000001 




000001 



90 

.ENDC 



91 

.13 N0 

0 


92 00436 

116710 

MOVB 

0, 701 


000000* 



93 

• ENDC 



94 

.13 NB 



95 


MOV 

,2,(0) 

96 

.ENDC 



97 

.13 NB 



98 


MOV 

*4*. £0) 

99 

.I3F 



100 0462 

005060 

CLP 

4.70) 


000004 



101 

.ENDC 



10? 0466 

104375 

3MT 

*0373 

103 

.ENDC 



104 0470 

005001 

CLP Pi 

761OCK NUMBEP 

1 05 

1 

'.R3A0 RAPE A . #0« 

#BU3R,#?56.,R1 

106 

.13 OF 

.‘..VI 


107 

.13 NB 

#256, 
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.MAIN. RT»11 MACRO V8H2-19I PAGE 1* 


10S 


.ENDC 


MOV 

4254.,X0 

104 




41,-(6.5 

110 




MOV 

111 




MOV 

4BUER,-(4.5 

11? 




MOV 

•0,•(6,5 

113 




PMT 

W O«2P0*4AREA* 

114 


.I7F 




115 


.IP N0 

# ARP A 



114 

0472 

012700 


MOV 

4APEA.X0 



000200* 




UT 

0476 

112760 

000010 

000001 


MOVB 

48’., 1(05 

11? 


.ENDC 




114 


.IP N0 

#* 



120 

0504 

112710 

000000 


MOVB 

40.(0) 

121 


.ENOC 




122 


• IP nb 

R1 



123 

0510 

010160 

000002 


MOV 

R l. 2. (0 5 

124 


.ENOC 




125 


.IP nb 

#RUFR 



124 

0514 

012760 

000220* 

000004 


MOV 

4BUFR.4,(05 

127 


.ENDC 




12« 


.IP nb 




124 

05?2 

012760 

000400 

000006 


MOV 

4256.,4.(05 

130 


.ENDC 




131 

0530 

012760 

000001 

000010 


MOV 

41,8.(05 

13? 

0534 

104375 


PMT 

*0375 

133 


.ENDC 




134 

0540 

000000 

HALT 



135 


000432* 

;end 

start 



V802-10 PAGE 1* 


.MAIN, RT*l 1 MACRO 


SYMBOL 

TABLE 


A 

000436R 

002 

§UPR 

000220R 

002 

R1 « 

1X000001 


STACK 

000000R 

002 

. AB8. 

000000 

000 


000000 

001 

main 

000542 

002 

ERRORS 

DETiCTEDi 

0 

FREE CORE 1 14088 

, WORDS 


AREA 0002O0R 002 

TNRLK 000420R 002 

SP «X000006 
START 000432R 002 


R 0004A0R 002 

PC «X00000T 
SORT ■ ****** G 
. V? • 000001 


,lpmtpst.pal 
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11.2 ASEMBL ERROR MESSAGES 


The system error 
follows: 

messages output for ASEMBL are abbreviated as 

Abbreviation 

Explanation 

?BSW? 

The switch specified was not recognized by the 
program. 

7C0RE? 

There are too many symbols in the program being 
assembled. Try dividing program into separately 
assembled subprograms. 

?NIF? 

No input file was specified and there must be at 
least one input file. 

?ODF? 

No room to continue writing output; try to 

compress device with PIP. 

?TMO? 

Too many output files were specified. 
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CHAPTER 12 


BATCH 


12.1 INTRODUCTION TO RT-11 BATCH 

RT-11 BATCH is a complete job control language that allows RT-11 to 
operate unattended. RT-11 BATCH processing is ideally suited to 
frequently run production jobs, large and long running programs, and 
programs that require little or no interaction with the user. Using 
BATCH, the user can prepare his job on any RT-11 input device and 
leave it for the operator to start and run. 

RT-11 BATCH provides the ability to: 

• Execute an RT-11 BATCH stream from any legal RT-11 input 
device. 

• Output a log file to any legal RT-11 output device (except 
magtape or cassette). 

• Execute the BATCH stream either with the Single-Job Monitor or 
in the background with a Foreground/Background Monitor. 

• Generate and support system independent BATCH language jobs. 

• Execute RT-11 monitor commands from the BATCH stream. 

RT-11 BATCH consists of two main sections: the BATCH compiler and the 
BATCH run-time handler. The BATCH compiler reads the batch input 
stream created by the user, translates it into a format suitable for 
the RT-11 BATCH run-time handler, and stores it in a file. The BATCH 
run-time handler takes the file generated by the compiler and executes 
it in conjunction with the RT-11 monitor. As each command in the 
batch stream is executed, the command, along with any terminal output 
generated by executing the command, is output to the BATCH log device. 


12.1.1 Hardware Requirements to Run BATCH 

RT-11 BATCH can be run on any Single-Job system configured with at 
least 12K words of memory. A minimum system of 16K words of memory is 
required to run BATCH in a Foreground/Background environment. A line 
printer, although optional, is highly desirable as the log device. 
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12.1.2 Software Requirements to Run BATCH 

BATCH uses certain RT-11 system programs to perform its operations. 
For example, the $BASIC command runs BASIC.SAV. The user must ensure 
that the following RT-11 programs are on the system device, with 
exactly the following names, before running BATCH. 


BASIC.SAV 
BA.SYS 
BATCH.SAV 
CREF.SAV 
FORLIB•OBJ 
FORTRA.SAV 
LINK.SAV 
MACRO.SAV 
PIP.SAV 


(BASIC users only) 


(MACRO users only) 
(FORTRAN users only) 
(FORTRAN users only) 

(MACRO users only) 


12.2 BATCH CONTROL STATEMENT FORMAT 

Input to RT-11 BATCH is either a file generated using the RT-11 Editor 
and input from any legal RT-11 input device, or punched cards input 
from the card reader. In both cases, the input consists of BATCH 
control statements. A BATCH control statement consists of three 
fields, separated from one another with spaces: command fields, 
specification fields, and comment fields. The control statement has 
the form: 

$command/switch specification/switch !comment 

Each control statement requires a specific combination of command and 
specification fields and switches (see Section 12.4). Control 
statements may not be longer than 80 characters, excluding multiple 
spaces, tabs, and comments. A line continuation character (-) may be 
used to indicate that the control statement is continued on the next 
line (see Table 12-4). Even if the line continuation character is 
used, the maximum control statement length is still 80 characters. 

The following example of a $FORTRAN command illustrates the various 
fields in a control statement. 

,$ FORTRAN/LI ST/RUN, ,PROG A/LIBRARY PROGB/EXE, ! RUN FORTRAN, 

, ^ - , 

command/switches spec fields/switches comment field 


12.2.1 Command Fields 

The command field in a BATCH control statement indicates the operation 
to be performed. It consists of a command name and certain command 
field switches. The command field is indicated by a $ in the first 
character position and is terminated by a space, tab, blank, or 
carriage return. 


12.2.1.1 Command Names — The command name must appear first in a 
BATCH control statement. All BATCH command names have a dollar sign 
($) in the first position of the command, e.g., $JOB. No intervening 
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the $FORTRAN command may be entered as: * C ° mmand name * For example, 
$FORTRAN 
or 
$FOR 

but cannot be entered as: 

$FORT 

or 

$FORTR 


12.2.i, 2 Command Field Switches — Switches that appear in a command 

pnnJ d . command qualifiers and their functions apply to the entire 

control statement. All switch names must begin witha slash (/) that 
immediately follows the command name. Table 12-1 describes £he 
command field switches that are legal in BATCH and indicates the 
commands on which they can be used. Those switch characters that 
appear in braces are optional. These switches will be mentioned aqain 
used^ he Sectlons P ert aming to the commands with which they can be 

!omma?d.°^ tC *“' S "°“™ heC °”""^ S,a ^ Ce ^ e /OBJECT A switch*in* 1 the n $LINK 



Table 12-1 

Command Field Switches 

Switch 

Function 

/ban{ner} 

Print header of job on the log file. This switch is 

allowed only on the $JOB command. 

/NOBAN{NER} 

Do not print a job header. 

/CRE{F} 

Produce a cross reference listing during compilation. 
This switch is allowed only on the $MACRO command. 

/NOCRE{F} 

Do not create a cross reference listing. 

/DEL(ETE} 

This te ^V ileS a f, ter , the operation is complete. 
This switch is allowed on the $COPY and SPRINT 

commands. 

/NODEL{ETE} 

Do not delete input files after operation is complete. 


(continued on next page) 
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Table 12-1 (cont.) 
Command Field Switches 


Switch 

Function 

/DOL{LARS} 

The data following this command may have a $ in tne 

first character position of a line. This switch is 
allowed on the $CREATE, $DATA, $FORTRAN, and $MACRO 
commands. Reading of the data is terminated by one of 
the following BATCH commands: 


$ JOB 

$SEQUENCE 

$EOD 

$EOJ „ 


or by a physical end-of-file on the BATCH input stream. 

/NODOL{LARS} 

Following data may not have a $ in the first character 
position; a $ in the first character position 
signifies a BATCH control command. 

/LIB{RARY} 

Include the default library in the link °P er ftion. 
This switch is allowed on the $LINK and $MACRO 

commands. 

/NOLIB{RARY} 

Do not include the default library in the link 

operation. 

/LIS{T> 

Produce a temporary listing file (see Section 12.2.5) 
on the listing device (LST:) or write data images on 
the log device (LOG:), This switch is allowed °n the 
$BASIC, $CREATE, $DATA, $FORTRAN, $JOB, and $MACRO 
commands. When used on the $JOB command, /LIST sends 
data lines in the job stream to the log device (LOG:). 

/nolis{t} 

Do not produce a temporary listing file. 

/MAP 

Produce a temporary linkage map on the listing device 
(LST:). This switch is allowed on the $FORTRAN, $LINK, 
and $MACRO commands. 

/NOMAP 

Do not create a MAP file. 

/OBJ{ECT} 

Produce a temporary object file as output of 
compilation or assembly (see Section 12.2.5). This 
switch is allowed on the $FORTRAN, $LINK, and $MACRO 
commands. When used on $LINK, this switch means that 
temporary files are to be included in the link 
operation. 

/NOOBJ{ECT} 

Do not produce object file as output of compilation, 
or, on $LINK, do not include temporary files in the 
link operation. 

/RT11 

Set BATCH to operate in RT-11 mode (see Section 12.5). 
This switch is allowed only on the $JOB command. 

/NORTH 

Do not set BATCH to operate in RT-11 mode. 


(continued on next page) 
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Table 12-1 (cont.) 

Command Field Switches 

Switch 

Function 

/RUN 

Link (if necessary) and execute programs compiled since 

the last "link-and-go" operation or start of job. This 
switch is allowed on the $BASIC, $FORTRAN, $LINK, and 
$MACRO commands. 

/NORUN 

Do not execute or link and execute the program after 
performing the specified command. 

/TIM{E} 

Write the time of day to the log file when commands are 
executed. This switch is allowed only on the $JOB 
command. 

/NOTIM{E} 

Do not write time of day to log file. 

/UNI{QUE} 

Check for unique spelling of switches and keynames (see 
Section 12.4.13). This switch is allowed only on the 
$JOB command. 

/NOUNI{QUE} 

Do not check for unique spelling. 

/WAI(T} 

Pause to wait for operator action. This switch is 
allowed on the $DISMOUNT, $MESSAGE, and $MOUNT 
commands. 

/NOWAI(T) 

Do not pause for operator action. 

/WRI{TE } 

Indicate that the operator is to WRITE-ENABLE a 
specified device or volume. This switch is allowed 
only on the $MOUNT command. 

/NOWRI{TE} 

Indicate that no writes are allowed or that the 
specified volume is read-only; the operator is 
informed and must WRITE-LOCK the appropriate device. 


12.2.2 Specification Fields 

Specification fields immediately follow command fields in a BATCH 
control statement and are used to name the devices and files involved 
in the command. These fields are separated from the command field, 
and from each other, by blanks or spaces. 

If a specification field contains more than one file to be used in the 
same operation, the + operator is used between these files. For 
example, to assemble files Fl and F2 to produce an object file F3 and 
a temporary listing file, type: 

$MACRO/LIST F1+F2/S0URCE F3/0BJECT 

If a command is to be repeated for more than one field specification, 
the operator is used between these files. For example, the 

following command assembles Fl to produce F2, a temporary listing 

file, and a map file F3. It then assembles F4 and F5 to produce F6 
and a temporary listing file. 

$MACRO/LIST FI/SOURCE F2/0BJECT F3/MAP, F4+F5/SOURCE- 
F6/OBJECT 
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Note that the command field switches apply to the entire line, but the 
specification field switches apply only to the field they follow. 

Depending on the command being used, specification fields may contain 
a device specification, file specification, or an arbitrary ASCII 
string. Any of these three may be followed by an appropriate 
specification field switch (see Table 12-3). 


12.2.2.1 Physical Device Names — Each device in an RT-11 BATCH 
specification field is referenced by means of a standard 2- or 
3-character device name. Table 2-2 in Chapter 2 lists each name and 
its related device. If no unit number is specified for devices which 
have more than one unit, unit 0 is assumed. 

In addition to the permanent names shown in Table 2-2, devices can be 
assigned logical device names. A logical device name takes precedence 
over a physical name and thus provides device independence. With this 
feature, a program that is coded to use a specific device does not 
need to be rewritten if the device is unavailable. For example, DK: 
is normally assigned to the system device, but that name can be 
assigned to DECtape unit 0 with an RT-11 monitor ASSIGN command. 

Certain logical names must be assigned prior to running any BATCH job 
since BATCH uses them as default devices. These devices are: 

LOG: BATCH log device (cannot be magtape or cassette) 

LST: default for listing files generated by BATCH stream 

The following are not legal device names in RT-11? if used, the 
operator must assign them as logical names with the ASSIGN command. 
These names are included here because they can be used in BATCH 
streams written for other DIGITAL systems. 


DF: 

Fixed-head disk (RF). 


LL: 

Line printer with upper and 
characters. 

lower case 

M7: 

7-track magtape. 


M9: 

9-trac1< magtape. 


PS: 

Public storage (DK: as assigned 

by RT-11). 


Refer to Sections 2.7.2.4 and 12.7.1 for instructions on assigning 
logical names to devices. 


12.2.2.2 File Specifications — Files are referenced symbolically in 
a BATCH control statement by a name of up to six alphanumeric 
characters followed, optionally, by a period and an extension of three 
alphanumeric characters. The extension to a file name generally 
indicates the format of a file. In most cases, it is a good practice 
to conform to the standard file name extensions for RT-11 BATCH. If 
an extension is not specified for an output file, BATCH and most other 
RT-11 system programs assign appropriate default extensions. If an 
extension for an input file is not specified, the system searches for 
that file name with a default extension. Table 12-2 lists the 
standard extensions used in RT-11 BATCH. 
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Table 12-2 

File Name Extensions 


Extension 

Meaning 

.BAS 

BASIC source file (BASIC input). 

.BAT 

BATCH command file. 

. CTL 

BATCH control file generated by the BATCH 

compiler. 

. CTT 

BATCH temporary file generated by the BATCH 

compiler. 

.DAT 

BASIC or FORTRAN data file. 

.DIR 

Directory listing file. 

.FOR 

FORTRAN IV source file (FORTRAN input). 

. LST 

Listing file. 

.LOG 

BATCH log file. 

.MAC 

MACRO or EXPAND source file (MACRO, EXPAND, SRCCOM 
input). 

.MAP 

Linkage map output from $LINK operation. 

.OBJ 

Object file, output from compilation or assembly. 

.SOU 

Temporary source file. 

.SAV 

$RUNable file or program image output from $LINK. 


12.2.2.3 Wild Card Construction — The wild card construction means 
that the file name or extension in certain BATCH control statements 
(i e , $COPY, $CREATE, $DELETE , $DIRECTORY, $PRINT) may be replaced 
totally with an asterisk (*). The asterisk is used as a wild card to 
designate the entire file name or extension. See Chapter 4, Section 
4 . 1 . 1 , for a complete description of the wild card construction. 


12.2.2.4 Specification Field Switches — Specification field switches 
follow file specifications in a BATCH control statement and designate 
how the file will be used. These switches apply only to the field in 
which they appear. Switch names begin with a slash. The 
specification field switches legal in RT-11 BATCH are listed in Table 
12-3. Optional characters in the switch names are shown in braces. 
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Table 12-3 

Specification Field Switches 


Switch 

Function 

/BAS{IC} 

BASIC source file. 

/EXECUTABLE} 

Indicates the runnable program image file to be created 
as the result of a link operation. 

/FOR{TRAN} 

FORTRAN source file. 

/INP(UT) 

Input file; default if no switches are specified. 

/lib{rary} 

Library file to be included in link operation (prior to 
default library). 

/LIS{T} 

Listing file. 

/LOGilCAL} 

Indicates that the device is a logical device name; 
used in $DISMOUNT and $MOUNT commands. 

/MAC{RO} 

MACRO or EXPAND source file. 

/MAP 

Linker map file. 

/OBJ{ECT} 

Object file (output of assembly or compilation). 

/OUT{PUT} 

Output file. 

/PHYSICAL} 

Indicates physical device name. 

/SOU{RCE} 

Indicates source file. 

/VID 

Volume identification. 


12.2.3 Comment Fields 


Comment fields, used to document a BATCH stream, are identified by an 
exclamation point (!) appearing anywhere except the first character 
position in the control statement. Any character following the ! and 
preceding the carriage return/line feed combination is treated as a 
comment and is ignored by the BATCH processor. For example, the 
following command: ^ 


$RUN PIP !DELETE FILES ON DK: 

runs the RT-11 system program PIP; the comment is ignored. 



$!DELETE FILES ON DK: 


12.2.4 BATCH Character Set 


The RT-11 BATCH character 
characters (i.e., ASCII 40 
assumed (i.e., character 137 


set is limited to the 64 upper—case 
through 137) . The current ASCII set is 
is underscore and not left arrow, and 
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character 136 is circumflex, not up-arrow). No control characters 
other than tab, carriage return, and line feed are supported by the 
BATCH job control language. 

Table 12-4 details the way in which BATCH normally interprets certain 
characters. Character interpretations are different when RT-11 mode 
is used (see Section 12.5). 


Table 12-4 

Character Interpretation 


Character 

Interpretation 

blank/space 

Specification field delimiter. Separates arguments in 
control statements. Any string of consecutive spaces 
and tabs (except in quoted strings) is considered a 
blank and is equivalent to a single space. 

i 

Comment delimiter. All characters after the 
exclamation point are ignored by the input routine, up 
to the carriage return/line feed. 

ii 

Used to pass a text string containing delimiting 
characters where the normal precedence rules would 
create the wrong action, e.g., to include a space in a 
volume identification (/VID). 

$ 

BATCH control statement recognition character. A 
dollar sign ($) in the first character position of a 
BATCH input stream line indicates that the line is a 
control statement. 

• 

Delimiter for file extension (type). 

- 

Indicates line continuation if the character after the 
hyphen is one of the following: 


• a carriage return/line feed 

• any number of spaces followed by a carriage 

return/line feed 

• a comment delimiter (!) 

• spaces followed by a comment delimiter (!) 


If any other character follows the hyphen, the hyphen 
is assumed to be a minus sign indicating a negative 
value in a switch. 

/ 

Start of a switch name. Must be followed immediately 
by an alphanumeric string. 

0-9 

Numeric string components. 

5 

Immediately follows a device name. Also can be used to 
separate a switch name from its value or to separate a 
switch value from its subvalue (: can be used 
interchangeably with = for this). 

A-Z 

Alphabetic string components. 


(continued on next page) 
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Table 12-4 (cont.) 

Character Interpretation 

Character 

Interpretation 

= 

Separates switch name from value. 

\ 

Illegal character except when preceding a directive 
to the BATCH run-time handler from the operator. 

(To include \ in an RT-11 mode command, use .) 

+ 

Delimiter separating multiple files in a single 
specification field. Also used to indicate a positive 
value in switches. 

r 

The comma (,) is used to separate sets of arguments for 
which the command is to be repeated. 

* 

The * is used as a wild card in utility command file 
specifications. 

CR/LF 

Carriage return/line feed. Indicates end-of-line (or 
end of logical record) for records in the BATCH input 
stream. 


12.2.5 Temporary Files 

When field specifications are not included in a BATCH command line, 
BATCH sometimes generates temporary files. For example, a $FORTRAN 
command which is followed in the BATCH stream by the FORTRAN source 
program could be entered as: 

$FORTRAN/RUN/OBJECT/LIST 
FORTRAN source program 

$EOD 


This command generates a temporary source file from the source 
statements that follow, a temporary object file, a temporary listing 
file, and a temporary save image file. 


BATCH sends temporary files to the default device (DKs) or the listing 
device (LST:) according to their nature. If the device is 
file-structured, BATCH assigns file names and extensions as follows: 


nnnmmm.LST 

for 

temporary 

nnnmmm.MAP 

for 

temporary 

nnnppp.OBJ 

for 

temporary 

nnnppp.SAV 

for 

temporary 

nnnppp.SOU 

for 

temporary 


where: 


listing files (sent to LST:) 
map files (sent to LST:) 
object files (sent to DK:) 
save image files (sent to DK:) 
source files (sent to DK:) 


is the last three digits of the sequence number 
assigned to the job by the $SEQUENCE command (see 
Section 12.4.22). Thus, a sequence number of 12345 
produces a file name beginning 345. If no $SEQUENCE 
command is used, nnn is set to 000. 


January 1976 
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mmm 


PPP 


is the mth listing (or map) file since the BATCH 
run time handler (BA.SYS) was loaded. The first such 
file, listing or map, is 000. Each time a new 

temporary file is generated, the file name is 
incremented by 1. Thus, the second listing file 
under job sequence number 12345 is 
and the firSt map file Produced is 

is the pth object, save image, or source file in the 
current BATCH run. The first such file (object, save 
image, or source) is 000. Each time a new temporary 
fiie is generated, the file name is incremented by 1. 
These file names are reset to 000 every time that 
BATCH is run and after every $LINK, $MACRO, or 
?FORTRAN command that uses the temporaries. 


12.3 General Rules and Conventions 

I«Lu° ll0Wln9 ’ 9eneral rules and conventions are associated with RT-11 
dailh processing. 

1. A dollar sign ($) is always in the first character position 
of a command line. 


Each job must have a $JOB and $EOJ command (or card). 

Command and switch names can be spelled out entirely or the 
first three characters of the command and required characters 
of the switch can be specified. 

Wild card construction (*) can be specified only for the 
$PRINT Y C ° mmandS: $COPY, $CREATE, $DELETE, $DIRECTORY, and 


5. 


Comments can be included at the end of command lines or in a 
separate comment line. When comments are included in a 
command line, they must follow the command and be preceded bv 
an exclamation mark. 


are 


Only 80 characters per control statement (card record) 
allowed, excluding multiple spaces, tabs, and comments. 

When file specifications are omitted from BATCH commands and 
data is supplied in the BATCH stream, the system creates a 
temporary file with a default name (see Section 12.2.5). 

The RT-11 monitor type-ahead feature is restricted to BATCH 
directives (see Section 12.7.3) to be inserted into a 
P ro 9 ram. No other terminal input (except to the 
foreground) can be entered while a BATCH stream is executing. 
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12.4 BATCH COMMANDS 

BATCH commands are placed in the input ^ream to indicate to the 
qvstem which functions to perform in the 30 b. All BATCH commanas 
a Y dollar sign ($) in the first character position of the command, 
e.g!, $5 ob. intervening spaces are not allowed in command names. The 
command name must always start in the first character posi ion 
line (card column 1 ). 

BATCH commands are presented in alphabetical order ir ? may 

ease of reference. However, a user who is unfamiliar with BATCH may 
prefer to read the commands in a functional order as detailed in Table 
12-5. The characters shown in braces are optional. 


Table 12-5 
BATCH Commands 


Command 

Section 

Function 

$SEQ{UENCE} 

12 . 4.22 

Assigns an arbitrary identification number 

to a job. 

$JOB 

12.4.13 

Indicates the start of a job. 

$EOJ 

12.4.11 

Indicates the end of a job. 

$MOU{NT> 

12.4.18 

Signals the operator to mount a volume on a 
device and optionally assigns a logical 



device name. 

$DIS{MOUNT} 

12.4.9 

Signals the operator to dismount a volume 
from a device and deassigns a logical device 



name. 

$for{tran} 

12.4.12 

Compiles a FORTRAN source program. 

$BAS{IC} 

12.4.1 

Compiles a BASIC source program. 

$MAC{RO} 

12.4.16 

Assembles a MACRO source program. 

$lib{rary} 

12.4.14 

Specifies libraries that are to be used in 
linkage operations. 

$LIN{K} 

12.4.15 

Links modules for execution. 

$RUN 

12.4.21 

Causes a program to execute. 

$CAL{L} 

12.4.2 

Transfers control to another BATCH file, 
executes that BATCH file, and returns to the 



calling BATCH stream. 

$CHA{IN} 

12.4.3 

Passes control to another BATCH file. 

$DAT{A} 

12.4.6 

Indicates the start of data. 

$EOD 

12.4.10 

Indicates the end of data. 

$mes{sage} 

12.4.17 

Issues a message to the operator. 


(continued on next page) 
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Table 12-5 (cont.) 
BATCH Commands 


Command 

Section 

Function 

$COP{y } 

12.4.4 

Copies files. 

$cre{ate} 

12.4.5 

Creates new files from data included in 
BATCH stream. 

$DEL{ETE} 

12.4.7 

Deletes files. 

$DIR{ECTORY} 

12.4.8 

Provides a directory of the specified 

device. 

$PRI{NT} 

12.4.19 

Prints files. 

$RT1{1} 

12.4.20 

Specifies that the following lines are RT-11 
mode commands. 


$ BASIC 


12.4.1 $BASIC Command 

The $BASIC command calls RT-11 Single-User BASIC to execute a BASIC 
source program. The $BASIC command has the following format: 

$BASIC{/switch} {dev:filnam.ext/sw} {Icomments} 
where: 

/switch indicates the switches that can be appended to the 

$BASIC command. The switches are as follows: 

/RUN indicates that the source program is to 

be executed. 

/NORUN indicates that the program is to be 

compiled only; error messages are sent 
to the log file. 

/LIST writes data images that are contained in 

the job stream to the log file (LOG:). 
/NOLIST writes data images to the log file only 

if $JOB/LIST was specified. 

dev:filnam.ext 

indicates the name of the source file and the device 
on which it resides. If dev: is omitted, DK: is 
assumed. If ext is omitted, the extension .BAS is 
assumed. If this specification is omitted, the 
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source statements must immediately follow the $BASIC 
command in the input stream. 


The source program included after a $BASIC statement 
can be terminated either by a $EOD command or by any 
other BATCH command that starts with a $ in the first 
position. 


/sw 


indicates the switches that may follow the source 
file name. Any file name with no switch appended is 
assumed to be the name of a source file. This switch 
can have one of the following values or can be 
omitted. 


/BASIC 


indicates that the file name specified 
is a BASIC source program, 
performs the same function as /BASIC, 
performs the same function as /BASIC. 


/SOURCE 

/INPUT 


The $BASIC command can be followed by the source program, by legal 
BASIC commands such as RUN, and by data. The following two BATCH 
streams, for example, produce the same results. 


SBfiSIC 

10 INPUT rl 

20 PRINT ft 

30 END 

RUN 

123 

*E0D 


SBftSICVRUN 

10 INPUT R 

20 PRINT ft 

30 END 

SDRTft 

123 

SEOD 


$CALL 


12.4.2 $CALL Command 

The $CALL command transfers control to another BATCH control file, 
temporarily suspending execution of the current control file. The 
CALLed file is executed until $EOJ is reached or until the job aborts; 
control then returns to the statement following the $CALL in the 
originating BATCH control file. Calls can be nested up to 31 levels. 
The log file for the CALLed BATCH file is included in the log file for 
the originating BATCH program. 

The format of the $CALL command is : 

$CALL dev:filnam.ext {{comments} 

No switches are allowed in the $CALL command. $JOB command switches 
are saved across a $CALL but do not apply to the called BATCH file. 
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If •CTL is specified as the file extension, a precompiled BATCH 
control file is assumed. If no .ext is specified, .BAT is assumed, 
and the called BATCH stream is compiled before execution. 

Please note that if the program called generates temporary files, 
those files may supersede currently existing temporary files if the 
two jobs have the same sequence number. For example, consider the 
following two BATCH streams: 


$ FOR/0 BJ fi 
$ F 0 R/OBJ B 
SLINK/RUN 


3FQR/0BJ R 
SCRLL C 
$ F 0 R / 0 B J B 
SL. INK/RUN 


The called BATCH file (C.BAT) contains the following: 


$ JOB 

$FOR/OBJ R1 
$FOR/ 0 BJ B1 
S L IN K / R U N 
*E0,T 


The temporary object files generated by C.BAT would change the 
behavior of the above two BATCH statement sequences since the first 
temporary file created by C.BAT (000000.OBJ) would supercede the 
temporary file produced by the first $FORTRAN command (000000.OBJ). 
This could be prevented by giving the BATCH job C.BAT a unique 
sequence number (see Section 12.4.22). 


$CHAIN 


12.4.3 $CHAIN Command 

The $CHAIN command transfers control to a named BATCH control file but 
does not return to the input stream which executed the $CHAIN command. 
The format of the $CHAIN command is: 

$CHAIN dev:filnam.ext {Icomments} 

No switches are allowed in the $CHAIN command. If .CTL is specified 
as the file extension, a precompiled BATCH control file is assumed. 
If no .ext is specified, .BAT is assumed, and the chained BATCH stream 
is compiled before execution. 

An $EOJ command should always follow the $CHAIN command in the BATCH 
stream. 
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NOTE 

The values of BATCH run-time variables 
remain constant across a $CALL, $CHAIN, 
or return from call. See Section 
12.5.2.2 for a description of these 
variables. 


The $CHAIN command is useful for transferring control to programs that 
need only be run once at the end of a BATCH stream. For example, the 
following BATCH program (PRINT.BAT) could be used to print and then 
delete all temporary listing files generated during the current BATCH 
job. 

SJOB !PR I NT ALL LIST FILES 

SPRINT/DELETE *. LST 

SEGJ 

PRINT.BAT can then be run with the $CHAIN command, e.g., 

SJOB 

SMACRO/RUN/LIST F1LE1, FILES* FILES 

SCHfilN PRINT 

SEOJ 


$COPY 


12.4.4 $COPY Command 

The $COPY command copies files in image mode from one device to 
another. The wild card construction (see Section 12.2.2.3) can be 
used in the input and output file specifications. More than one input 
file can be concatenated to form one output file so long as the output 
specification does not contain a wild card. The $COPY command has the 
following format. 

$COPY{/switch} dev:filnam.ext/OUTPUT dev:filnaml.ext{/INPUT}- 
{Icomments} 


where: 

/switch indicates switches that can be appended to the $COPY 

command. 

/DELETE indicates that input files are to be 

deleted after the copy operation. 
/NODELETE indicates that input files are not to be 
deleted after the copy operation. 
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dev: 


filnam 


ext 


/OUTPUT 

filnaml 


/INPUT 


indicates the device containing the files to be 
copied for the input portion of the command or the 
device to which the files are to be copied for the 
output portion of the command. If dev: is not 
specified, DK: is assumed. 

indicates the name to be assigned to the output file; 
a wild card may be used instead of an explicit file 
name. Additional output files can be specified if 
they are separated from each other with commas. 

indicates the file extension and must be specified. 
For input files, a wild card can be used instead of 
an explicit extension. For output files, wild cards 
can be used so long as no concatenation is specified. 

is appended to a file specification to indicate that 
it is for the output file. 

specifies the name of the input file. Wild cards can 
be used instead of an explicit file name. Additional 
input files can be specified if they are separated 
from each other with commas. Files are copied to the 
output file in the order specified. 

is appended to the input file specifier(s). The 
system assumes input if no switch is used. 


The following are examples of the $COPY command: 

SCGPY *. BftS/GUTPUT Oil BflS 

The above command copies all files with the extension .BAS from the 
DECtape on unit 1 to the default storage device DK. 

SCOPY FILES FOR/OUTPUT FILES. FOR + FILEi. F0R 

The above command merges the input files FILEO.FOR and FILEl.FOR to 
form one file called FILE2.FOR and stores FILE2.FOR on device DK. 

SCGPY FILES. FOR + F ILO. FOK’/OUTPUT FIl ES. FOR + FIl El. FOR 

The above command copies. FILEO. FOR to DK: as FILE2. FOR and FILEl. FOR 
as FILE3.FOR. 


*CGPY *. +/0UT DIG:*. FOR,jTI* +/0UT CTO:* * 

The above command copies all files with the extension .FOR from DTO: 
to DK: and all files on DTO: to DTI:. 
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$CREATE 


12.4.5 $CREATE Command 

The $CREATE command generates a file consisting of data records from 
data that follows the $CREATE command in the input stream. An error 
occurs if the data does not immediately follow the $CREATE command. A 
$DATA command must not precede the data records. 


The data associated with $CREATE can be followed by a $EOD command to 
signify the end of data or any other BATCH control statement can be 
used to indicate end of data and initiate a new function. The $CREATE 
command has the following format: 


$CREATE{/switch} dev:filnam.ext {icomments} 
where: 


/switch 


dev: 


filnam 


ext 


indicates switches that can be appended to the 
$CREATE command. 


/DOLLARS 

/NODOLLARS 

/LIST 

/NOLIST 


indicates that the data following this 
command may have a $ in the first 
character position of a line, 
indicates that a $ may not be in the 
first character position of a line, 
writes data image lines to log file, 
does not write data image lines to log 
file. If $JOB/LIST was specified, this 
switch is ignored. 


device on 
specified 

which 

the file is to 

reside; DK: if 

not 

indicates 
file name 

the name to be assigned 
must be specified. 

to the file. 

The 

indicates 

the 

file extension. 

If extension 

is 

omitted, 

filnam 

must be followed 

by a period. 



The following is an example of the $CREATE command: 


SCREfiTE/LIST PROG.FOR 
FORTRAN source file 


*EGD 

The data records following the $CREATE command become a new file 
(PROG.FOR) on the default device (DK:) and a listing is generated on 
logical device LOG:. 


12-18 






BATCH 


$DATA 


12.4.6 $DATA Command 


The $DATA command is used to include data records in the input stream. 
No file name is associated with the data; the data is transferred to 
the appropriate program as though input from the console terminal. 
For example, the $RUN command for a particular program can be followed 
by a $DATA command and the data records to be processed by the 
program. The data records must be valid data for the program that is 
to use them. 

The $DATA command has the following format: 

$DATA{/switch} {!comments} 


Four switches can be used with the $DATA command. 


/DOLLARS 

/NODOLLARS 

/LIST 

/NOLIST 


indicates that the data following this command may 
have a $ in the first character position of a line, 
indicates that a $ may not be in the first character 
position of a line. 

writes data image lines to the log file. 

does not write data images to the log file. If 

$JOB/LIST was specified, this switch is ignored. 


An $EOD command normally follows the last data record. However, any 
other BATCH command may also signal the end of the data so long as 
$DATA/DOLLARS is not specified (see Table 12-1). 

The following example shows data being entered into a BASIC program 
(TEST1.BAS). 

C/RUN TEST 1.BBS 

*Dfi Tfi 

2 5 ? b t 1 2, 5 , 146 
1 88, 2 18, 528, 8? 4 
*E0D 
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12.4.7 $DELETE Command 

The $DELETE command is used to delete files from the specified device. 
This command has the form: 

$DELETE dev:filnaml.ext{, dev:filnam2.ext,...,dev:filnamn.ext}- 
{Icomments} 

where filnaml through filnamn are the names of the files to be 
deleted. The file name and extension are required. Wild cards can be 
used in the file name and extension positions. 

The following example deletes all files named TEST1 on the default 
device (DK:). 

^DELETE TEST1.* 

The following example deletes all files with .FOR extensions on DTI: 
then deletes all files with .MAC extensions on DK:. 

^DELETE DTI: *. FOR, *. MftC 


$ DIRECTORY 


12.4.8 $DIRECTORY Command 

The $DIRECTORY command outputs a directory of the specified device to 
a listing file. If no listing file is specified, the listing goes to 
the BATCH log file. Wild cards can be used in the specification 
fields. This command has the form: 

$DIRECTORY {dev:filnam.ext/LIST} {dev:filnam.ext}{/INPUT}- 
{Icomments} 
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where: 


/LIST 

/INPUT 


indicates name of directory listing file. 

{default^ input fiies to be included in directory 


The following are examples of the $DIRECTORY command: 
*DI RECTORY 


The above command outputs a directory of the device DK 
log file. 


to the BATCH 


^DIRECTORY FOR. DIR/LIST *. FOR 


The above command creates a directory file (FOR.DIR) on 
DK:. The directory contains the names, lengths, and dates 
of all FORTRAN source files on the device DK:. 


the device 
of creation 


^DISMOUNT 


12.4.9 $DISMOUNT Command 

The $DISMOUNT command removes the logical device name assigned by a 
$MOUNT command. When $DISMOUNT is encountered during the execution of 
a job, the entire $DISMOUNT command line is printed on the console 
terminal to inform the operator of the specific device to unload. 
This command has the form: 

$DISMOUNT{/switch} ldn:{/LOGICAL} {Icomments} 


where: 


/switch indicates the switches that can be appended to the 

$DISMOUNT command. 

/WAIT indicates that the job is to pause until 

the operator enters a response. If 
neither /WAIT nor /NOWAIT is specified, 
/WAIT is assumed. BATCH rings a bell at 
the terminal, prints the physical device 
name to be dismounted and a ?, and waits 
for a response. (Input to the BATCH 
handler can be entered, see Section 
12.7.3.) 

/NOWAIT does not pause for operator response. 

BATCH prints the physical device name to 
be dismounted. 
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is the logical device name to be deassigned from the 
physical device. 

/LOGICAL identifies the device specification as a logical 
device name. 


The following example instructs the operator 
device with the logical device name OUT 
assignment of device OUT. In^this case, OUT 
dismounts DTO and types a carriage return. 


to dismount the physical 
and removes the logical 
is DTO. The operator 


ISMOUNT/WfiIT OUT:/LOGICAL 
DTO? 


$EOD 


12.4.10 $EOD Command 

The $EOD command indicates the end of data record or the end of a 
source program in the job stream. The format of this command is: 

$EOD {Icomments} 

The $EOD command can signal the end of data associated with any of the 
following commands: 

$BASIC 
$CREATE 
$DATA 
$FORTRAN 
$MACRO 

The $EOD command in the following example indicates the end of a 
source program that is to be compiled, linked, and executed. 

^FORTRAN / RIJ N 

source program 


SEOD 
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$EOJ 


12.4,11 $EOJ Command 

The $EOJ command indicates the end of a job. This command must be the 
last statement in every BATCH job. The command has the following 
format: 

$EOJ {!comments} 

If a $JOB command, a $SEQUENCE command, or a physical end-of-file is 
encountered in the input stream before $EOJ, the error message NO $EOJ 
appears in the log file. 


$FORTRAN 


12.4.12 $ FORTRAN Command 

The $FORTRAN command calls the FORTRAN compiler to compile a source 
program. Optionally, this command can provide printed listings or 
list files and may produce a linkage map in the listing. The $FORTRAN 
command has the following format: 

$FORTRAN{/switch } {dev 2 filnaml.ext/sw } {dev:filnam2.ext/OBJECT }- 
{dev 2 filnam3.ext/LIST } {dev 2 filnam4.ext/EXECUTE}- 
{dev 2 filnam5.ext/MAP } {dev 2 filnam6.ext/LIBRARY } {Icomments } 

where 2 

/switch indicates the switches that can be appended to the 

$FORTRAN command. The switches are as follows: 

/RUN indicates that the source program is to 

be compiled, linked with the default 
library (initially FORLIB.OBJ, may be 
reset with the $LIBRARY command), and 
executed. 
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/NORUN 

/OBJECT 

/NOOBJECT 

/LIST 

/NOLIST 

/MAP 

/NOMAP 

/DOLLARS 

/NODOLLARS 


indicates that the program is to be 
compiled only. 

indicates that a temporary object file 
is to be produced. 

indicates that a temporary object file 
is not to be produced. 

indicates that a list file is to be 
produced on the listing device (LSTs). 
indicates that a list file is not to be 
produced. 

produces a linkage map on the listing 

device (LST:). 

does not create MAP file. 

indicates that the data following this 

command may have a $ in the first 

character position of a line. 

indicates that a $ may not be in the 

first character position of a line. 


dev:filnaml.ext 

indicates the device, file name, and extension of the 
FORTRAN source file. If filnaml is not specified, 
the $FORTRAN source statements must immediately 
follow the $FORTRAN command in the input stream; 
BATCH generates a temporary source file that is 
deleted after it is compiled (see Section 12.2.5). 

The source program included after a $FORTRAN 
statement can be terminated either by a $EOD command 
or by any other BATCH command so long as 
$FORTRAN/DOLLARS is not specified (see Table 12-1). 
A BATCH command is one that starts with a $ in the 
first position. 

/sw can have one of the following values or can be 

omitted: 

/FORTRAN indicates that the file name specified 

is a FORTRAN source program. Any file 
name with no switch appended is assumed 
to be the name of a source file. 

/SOURCE performs the same function as /FORTRAN. 

/INPUT performs the same function as /FORTRAN. 

dev:filnam2.ext/OBJECT 

indicates the device, file name, and extension of the 
object file produced by compilation. The object file 
remains on the specified device after the job 

finishes. The object file specification, if 

included, must be followed by the /OBJECT switch. 

If the object file specification is omitted but 
$FORTRAN/OBJECT is specified, a temporary object file 
is created, included in any $LINK operations that 
follow it in the job, and deleted after the link 
operation. 

dev:filnam3.ext/LIST 

indicates the name to be assigned to the list file 
created by the compiler. The list file is not 

printed automatically if LST: is assigned to a 
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file-structured device, but it can be listed using 
the $PRINT command. The list file specification must 
be followed by the /LIST switch. 

dev:filnam4.ext/EXECUTE 

indicates the name to be assigned to a save image 
file. The save image file specification must be 
followed by the /EXECUTE switch. If this field is 
not included, BATCH generates a temporary save image 
file (see Section 12.2.5) and then deletes the 
temporary file. 

dev:filnam5.ext/MAP 

indicates the name to be assigned to the linkage map 
file created by the Linker. The map specification 
must be followed by the /MAP switch. 

dev:filnam6.ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library before FORLIB.OBJ. 
The file must be a library file (produced by RT-11 
LIBR). The library specification must be followed by 
the /LIBRARY switch. 

The following are examples of $FORTRAN commands: 

3 FOR TRAN,•••'RUN PRGGft. FOR 

The above command calls FORTRAN to compile a source program named 
PROGA.FOR. The program is compiled and executed. 


$F 0 RTR flN/N00B J/LIST 
source program 


SEOD 

The above command sequence compiles the FORTRAN program but does not 
produce an object file. A temporary listing file is created on LST:. 


$JOB 


12.4.13 $JOB Command 

The $JOB command indicates the beginning of a job. Each job must have 
its own $JOB command. This command has the following format: 

$JOB{/switch}{/switch2}{/switchn} {!comments} 
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The switches allowed in the $JOB command are: 


/BANNER 

print header (a repetition of the $JOB command) on 
the log file. 

/NOBANNER 

do not print job header. 

/LIST 

write data image lines that are contained in the job 
stream to the log file. 

/NOLIST 

write data image lines to the log file only when a 
/LIST switch exists on a $BASIC, $CREATE, or $DATA 
command that has data lines following it. 

/RT11 

if no $ appears in column 1 when one is expected, 
assume that the line or card is an RT-11 mode command 
(see Section 12.5). 

/NORTH 

do not process RT-11 mode commands. 

/TIME 

write the time of day to the log file when command 
lines are executed (see NOTE on following page). 

/NOTIME 

do not write time of day. 

/UNIQUE 

check for unique spelling of switches and keynames. 
When this switch is used, commands and switches may 
be abbreviated to the least number of characters that 
still make their names unique. For example, the 
/DOLLARS switch can be abbreviated to /DO since no 
other switches begin with the characters DO. 

/NOUNIQUE 

check only for normal switch and keyname spellings. 


Each job must be ended with a $EOJ command if it is to be run. If an 
input stream consists of more than one job, BATCH automatically 
terminates one job when the $JOB command for the next job is 
encountered. A job terminated with another $JOB command will never be 
run; an error message (NO $EOJ) will appear in the log. 

The following $JOB command specifies that the time of day be written 
to the log file before each BATCH command beginning with a $ is 
executed and that unique abbreviations of BATCH commands and switches 
be accepted. 

SJG6VTI ME/UNIQUE 


January 1976 
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NOTE 

If the /TIME switch is used on the $JOB 
command, the $DATA command cannot be 
used. For example, this job will not 
run properly: 

*JOB/TIME 
*RUN PROG 
♦ DATA 
123 
$EOD 
*EOJ 


The /TIME switch uses the KMON TIME com¬ 
mand to print the current time on the log 
for each BATCH command, including $ DATA, 
causing an abort of the program that was 
to use the data. To avoid the problem, 
use RT-11 mode: 


$JOB/TIME 
*RT11 
♦R PROG 
*1.23 
*EOd 
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12.4.14 SLIBRARY Command 

The $LIBRARY command allows the user to specify a list of library 
files that will be included in FORTRAN links or with other linkage 
operations that specify the /LIBRARY switch. By default, the list of 
libraries contains only FORLIB.OBJ, the RT-11 FORTRAN library. This 
command has the form: 

$LIBRARY mylib {icomments} 

or 

$LIBRARY mylib+FORLIB {icomments} 


where: 

FORLIB is the RT-11 FORTRAN library and mylib is a user library. 
Libraries are linked in order of their appearance in the $LIBRARY 
command. 

The following example shows two user libraries (LIBl.OBJ and LIB2.0BJ) 
to be included in FORTRAN links before FORLIB.OBJ. 

SLIBRRRV LIEU. GBJ + LIB2. OBJ+FORLIB. OBJ 


$LINK 


12.4.15 $LINK Command 

The $LINK command is used to produce save image files from object 
files. This command links the specified files (if any) with all 
temporary object files created since the last link or "1ink-ana-go" 
operation (if any). 
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Temporary object files are those created as a result of a $FORTRAN or 
$MACRO command in which object files were neither specifically named 
by using the /OBJECT switch nor suppressed by using the /NOOBJECT 
switch. Permanent object files are created by using the /OBJECT 
switch on a $FORTRAN or $MACRO file descriptor. 

Files are linked in the following order: 

1. First, temporary files are linked in the order in which they 
were compiled. 

2. Then, permanent files are linked in the order in which they 
are specified in the $LINK command. 

3. If a library is specified in the $LINK command, it is linked 
next, providing that unresolved references remain. 

4. If $LINK/LIBRARY is specified, the default library list is 
searched and linked. 


The format for this command is: 

$LINK{/switch} {filnaml.ext/OBJECT} {filnam2.ext/LIBRARY}- 
{filnam3.ext/MAP} {filnam4.ext/EXECUTE} {!comments} 


where: 

/switch 


indicates the switches that can be appended to the 
$LINK command. The switches are as follows: 


/LIBRARY 


/NOLIBRARY 

/MAP 

/NOMAP 

/OBJECT 

/NOOBJECT 

/RUN 

/NORUN 


indicates that the FORTRAN library 
(FORLIB.OBJ) and any default libraries 
specified in the $LIBRARY command are to 
be included in this $LINK operation. 
This switch is normally used when the 
files being linked do not include any 
temporary FORTRAN object files or when 
$FORTRAN was specified without the /RUN 
or /MAP switch but the default library 
list is to be searched for unresolved 
references. 

Indicates that the default libraries are 
not to be included. 

produces a temporary load map on the 
listing device (LST:). 

indicates that a map file is not to be 
produced. 

indicates that temporary object files 
are to be included in the link. If 
neither /OBJECT nor /NOOBJECT is 
specified, $LINK/OBJECT is assumed, 
indicates that temporary files are not 
to be included in the link, 
indicates that the save image files 
associated with this $LINK command are 
to be executed when the link is 
complete. 

indicates that program linking only is 
to occur. 
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f ilnaml.ext/OBJECT 

indicates the name of the object file to be linked. 
If /OBJECT is not specified, it is assumed as the 
default. 

filnam2.ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library. The file 
specified must be a library file (produced by RT-11 
LIBR). 

filnam3.ext/MAP 

indicates the load map file to be created as a result 
of the $LINK command. 

filnam4.ext/EXECUTE 

indicates the save image file to be created as a 
result of the $LINK command. 

The following are examples of the $LINK command: 

*LINK/RUN 

The above command links all temporary object files created since the 
last $LINK command or the last $FORTRAN/OBJ or $MACRO/OBJ command. 

SLINK,'HAP F'RQGl. OBJ + PR0G2. OBJ F'ROGfl. SflV/EXE 

The above command links the temporary files and the object files 
PR0G1.OBJ and PROG2.OBJ to form a save image file named PROGA.SAV. It 
also creates and outputs a temporary map file. 


$MACRO 


12.4.16 $MACRO Command 

The $MACRO command calls the MACRO assembler to assemble a source 
program and, optionally, to provide printed listings or list files. 
MACRO listing directives, if any, must be specified in the source 
program to enable their use, as they cannot be entered at BATCH 
command level. 

The $MACRO command has the following format: 

$MACRO{/switch} {filnaml.ext/sw} {filnam2.ext/OBJECT}- 
{filnam3.ext/LIST} {filnam4.ext/MAP } {filnam5.ext/LIBRARY}- 
{filnam6.ext/EXECUTE} {‘comments } 

where: 
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/switch 


filnaml 


/sw 


filnam2 


indicates the switches that can be appended to the 
$MACRO command. The switches are as follows: 


/RUN 

/NORUN 

/OBJECT 

/NOOBJECT 

/LIST 

/NOLIST 

/CREF 

/NOCREF 

/MAP 

/NOMAP 

/DOLLARS 

/NODOLLARS 

/LIBRARY 

/NOLIBRARY 


indicates that the source program is to 
be assembled, linked, and run. 
indicates that the source program is to 
be assembled only. 

indicates that a temporary object file 
is to be produced. 

indicates that a temporary object file 
is not to be produced. 

indicates that a listing file is to be 
produced on the listing device (LST:). 
indicates that a list file is not to be 
produced. 

specifies that a cross reference listing 
is to be produced during assembly, 
indicates that a cross reference listing 
is not to be produced during assembly, 
produces a linkage map as part of the 
listing file on LST:. 
does not create MAP file, 
indicates that the data following this 
command may have a $ in the first 
character position of a line, 
indicates that a $ may not be in the 
first character position of a line, 
indicates that the default library is to 
be included in the link operation, 
indicates that the default library is 
not to be included in the link 
operation. 


ext 

indicates the name of the source file in the format 
dev:filnam.ext. If filnaml is not specified, the 
$MACRO source statements must immediately follow the 
$MACRO command in the input stream. 

The source program included after a $MACRO statement 
can be terminated either by a $EOD command or by any 
other BATCH command so long as $MACRO/DOLLARS is not 
specified. A BATCH command is one that starts with a 
$ in the first position. 

can have one of the following values or can be 
omitted: 

/MACRO indicates that the file name specified 

is a MACRO source program. Any file 
name with no switch appended is assumed 
to be the name of a source file. 

/SOURCE performs the same function as /MACRO. 

/INPUT performs the same function as /MACRO. 

.ext/OBJECT 

indicates the name (in the format dev:filnam.ext) to 
be assigned to the object file produced by 
compilation. 

The object file remains on the specified device after 
the job finishes. The object file specification, if 
included, must be followed by the /OBJECT switch. 
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If the object file specification is omitted but 
$MACRO/OBJECT is specified, a temporary object file 
is created, included in any $LINK operations that 
follow the $MACRO command in the job, and deleted 
after the link operation (see Section 12.2.5). 

filnam3.ext/LIST 

indicates the name to be assigned to the list file 
created by the assembler. The list file is not 
printed automatically if LST: is assigned to a 

file-structured device, but can be listed using the 
$PRINT command. The list file specification must be 
followed by the /LIST switch. 

filnam4.ext/MAP 

indicates the file to which the storage map is to be 
output. 

filnam5.ext/LIBRARY 

indicates that the specified file is to be included 
in the link procedure as a library. The library file 
specification must be followed by the /LIBRARY 
switch. 

filenam6.ext/EXECUTE 

indicates the name to be assigned to a save image 
file. The save image file specification must be 
followed by the /EXECUTE switch. If this field is 
not included, BATCH generates a temporary save image 
file (see Section 12.2.5), runs it, and then deletes 
the temporary file. 

The following $MACRO command assembles a program named PROGO.MAC and 
creates a temporary object file and a temporary listing file. 

♦MRCRO/LIST/OBJECT PR0G6. MAC 


$MESSAGE 


12.4.17 $MESSAGE Command 

The $MESSAGE command is used to issue a message to the operator at the 
console terminal. It provides a means for the job to communicate with 
the operator. The $MESSAGE command has the form: 

$MESSAGE{/switch} message {!comments } 

where: 
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/switch 


message 


indicates the switches that can be appended to the 
$MESSAGE command. These switches are: 

/WAIT indicates that the job is to pause until 

the operator types a carriage return to 
continue or enters commands to the BATCH 
handler followed by a carriage return 
(see Section 12.7.3). 

/NOWAIT do not pause for operator response. 

is a string of characters that must fit on one 
console line. The message is printed on the console. 


For example, if the following message is included in the input stream 
$MESSAGE/WAIT MOUNT SCRATCH TAPE ON MT0 


The message: 

MOUNT SCRATCH TAPE ON MT & 


appears on the console terminal and a bell 
mounts the tape and types carriage return to 
of the job. (See Section 12.7.3 for operator 


sounds. The operator 
allow further processing 
interaction with BATCH.) 


$MOUNT 


12.4.18 $MOUNT Command 


The $MOUNT command assigns a logical 
characteristics to a physical device, 
during the execution of a job, the entire 
printed on the console terminal to notify 
to be used. 


device name and other 
When $MOUNT is encountered 
$MOUNT command line is 
the operator of the volume 


The $MOUNT command has the form: 

$MOUNT{/switch} dev :{/PHYSICAL}{/VID=x} { ldn s/LOGICAL} {icomments} 
where: 

/switch indicates the switches that can be appended to the 

$MOUNT command. The switches are: 

/WAIT indicates that the job is to pause until 

the operator enters a response. If 
neither /WAIT nor /NOWAIT is specified, 
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/WAIT is assumed. BATCH rings a bell, 
prints a ?, and waits for a response. 
(The response can be input to the BATCH 
handler; see Section 12.7.3. 


does not pause for operator response. 


tells the operator to WRITE-ENABLE the 
volume. 


tells the operator to WRITE-PROTECT the 
volume. 

is required and specifies the physical device name 
and an optional unit number followed by a colon, 
e.g., DTI:. If dev is specified without a unit 
number, the operator can enter one in response to the 
? printed by the $MOUNT command. If the operator is 
to supply a unit number, do not use the /NOWAIT 
switch because it will assume unit 0. 


/NOWAIT 

/WRITE 

/NOWRITE 


/PHYSICAL identifies the device specification as a physical 
unit specification. if neither /PHYSICAL nor 
/LOGICAL is specified, /PHYSICAL is assumed. 


/VID=x 

/VID="x" 


provides volume identification. The volume identifi¬ 
cation is the name physically attached to the volume. 
It is included to help the operator locate the 
volume. This switch may appear only on the physical 
device file specification. If x contains spaces, it 
must be input as "x". 


ldn:/LOGICAL 

is required to identify the logical device name, if 
any, to be assigned to the device. The logical 
device name specification must be followed by the 
/LOGICAL switch. 

The following are examples of the $MOUNT command: 


AMOUNT / WAIT/WRITE D T : / VI D = B A T 01 2 : / L 0 GI C A L 

This command instructs the operator to select a DECtape unit and mount 
DECtape volume BAT01 on that unit, WRITE-ENABLED. It informs the 
operator by printing: 

*M 0UNT /WAIT/WRITE DT : / VID=6AT01 2 ■ /LnQI r .AL 
?1 


The operator selects a unit, mounts DECtape volume 
WRITE-ENABLED, and responds to the ? by typing the unit number 
1) followed by a carriage return. BATCH assigns logical device 
to the physical device (e.g., DTI:) and proceeds. 


BAT01, 
(e.g., 
name 2 


If no unit number response is necessary, e.g.. 


#MOUNT/WAIT/WRI TE DTI: 2 : /LOG I CAL 


the operator responds with a carriage return after 
DECtape and WRITE-ENABLING the device. 


mounting 


the 
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SPRINT 


12.4.19 $PRINT Command 

The $PRINT command is used to print the contents of the specified 
files on the listing device (LST:). This command has the form: 

$PRINT{/switch} dev:filnam.ext{/INPUT}{,dev:filnam2.ext,...,dev:- 
filnamn.ext} {!comments} 


where: 

indicates the switches that can be appended to the 
$PRINT command. The switches are: 

/DELETE indicates that input files are to be 

deleted after printing. 

/NODELETE indicates that input files are not to be 
deleted after printing. 

is the device containing the files to be printed; if 
dev: is not specified, DK: is assumed. 

filnaml.ext- 

filnamn.ext indicate names of the files to be printed. Wild 
cards can be used for the file name or extension. 

/INPUT indicates that the file is an input file; /INPUT is 

assumed if it is not entered. 

The following command prints a listing of files with extension .MAC 
that are stored on default device DK:. 

SPRINT *. MRC 

The following example creates listing files for the programs A and B f 
prints the listing files, and then deletes them. 

SMflCRO R. MAC A/LIST 
SMRCRO B. MRC 6/LIST 
SPRINT/DELETE R. LST, B. LST 


/switch 


dev: 
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12.4.20 $RT11 Command 

The $RT11 command allows the BATCH job to communicate directly with 
the RT-11 system. This command puts BATCH in RT-11 mode, i.e., until 
a line beginning with $ is encountered, all data images are 
interpreted as commands to the RT-11 monitor, RT-11 system programs, 
or to the BATCH run-time system. The $RTll command has the form: 

$RT11 {Icomments} 

See Section 12.5 for a complete description of the RT-11 mode. 


$RUN 


12.4.21 $RUN Command 

The $RUN command requests execution of a program for which a save 
image file (.SAV) was previously created. It can also be used to run 
RT-11 system programs. 

The $RUN command has the form: 

$RUN dev:filnam.ext {icomments} 

where filnam.ext is the name of the program (system or user) to be 
executed. If no extension is specified, .SAV is assumed. 

For example, the user can run PIP to print a directory listing. 

*RUN PIP 
SDftTfi 
LP:=DK:/L 
SEOD 
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12.4.22 $SEQUENCE Command 

The $SEQUENCE command is an optional command. If used, it must 
immediately precede a $JOB command. The $SEQUENCE command assigns a 
job an arbitrary identification number. The last three characters of 
a sequence number are assigned by BATCH as the first three characters 
of a temporary listing or object file (see Section 12.2.5). If a 
sequence number is less than three characters long, it is padded with 
zeroes on the left. 

The form of this command is: 

$SEQUENCE id {icomments} 

where id is an unsigned decimal number indicating the identification 
number of a job. 

The following are examples of the $SEQUENCE command: 

♦SEQUENCE 3 !SEQUENCE NUMBER IS 003 

$ JOB 

♦SEQUENCE 100 ! SEQUENCE NUMBER IS 100 

♦ J 0 B 


12.4.23 Example BATCH Stream 

The following example BATCH stream creates a MACRO program, assembles 
and links that program, and runs the save image file. It then deletes 
the object, save image, and source files created and prints a 
directory of DK: showing the files created by the BATCH stream. 


I 


$ JOB 

♦MESSAGE 
♦MESSAGE 
♦CREATE/LIST 
.TITLE 


START: 


MESSAGE 


THIS IS AN 
NOW CREATE 
EXAMPL. MAC 
EXAMPL FOR BATCH 
. MCALL .REGDEF,.. 

.REGDEF 
. . V2. . 

.PRINT # M E S S A G 
. EXIT 
.ASCI2 

. END START 


EXAMPLE 
A MACRO 


BATCH STREAM 
PROGRAM 


VcL. 


PRINT,.EXIT 


EXAMPLE MACRO PROGRAM FOR BATCH, 
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SEOD 

♦HRCRO EXRMPL EXflMPL/QBJECT EXfiMPL/LIST !ASSEMBLE 

$LINK EXAMPL EXRMPL,'EXECUTE !RND LINK 

SPRINT,'DELETE EXFIMPL. LST 

$MESSAGE RUN THE MACRO PROGRAM 

SRUN EXAMPL !AND EXECUTE 

SDELETE EXAMPL.OBJ+EXAMPL. SRV+EXAMPL.MAC 

^MESSAGE PRINT A DIRECTORV 

^DIRECTORS' DK : EXAMPL. * 

^MESSAGE END OF THE EXAMPLE BATCH STREAM 

SEOJ 

To run this batch stream, the user types the following at the console. 
Messages are printed by BATCH. 

. LOAD BA,LP 
.ASSIGN LP:LOG 
. ASSIGN LP:LST 
. R BATCH 
* EXAMPL 

THIS IS AN EXAMPLE BATCH STREAM 
NOW CREATE A MACRO PROGRAM 
RUN THE MACRO PROGRAM 
PRINT A DIRECTORS' 

END OF THE EXAMPLE BATCH STREAM 

END BATCH 

The above example BATCH stream produces the following log file on the 
line printer. 

5 JOB 

MESSAGE THIS IS AN EXAMPLE HATCH STREAM 

^MESSAGE N0 ‘i CREATE A MACRO PROGRAM 

SCREATE/LIST EXAmPL.RAC 

.TITLE EXAMPL FOR BATCH 

, ''CALL .REGOEF, ..V2.., .PRINT, .EXIT 
.RECDEF 

..V?.. 

START; .PRINT AMESSAG 

.EXIT 

MESSAGE t .A SC IZ /EXAMPLE MACRO PROGRAM FOR BATCH/ 

.END START 

T\ 

SEOD 

*MAC«0 EXAMPL EXAMPL/OBJECT EXAmP|./LIST JASSEMBLE 

★ERRORS DETECTED: 0 
FREE CORE: 1476A. RORDS 


$ LINK EXAMPL EXAMPL/EXFCUTE !AMD LINK 

SPRINT/DELETE EXAMP|_.LST 

smessase RUN the macro PROGRAM 

*R!."» Ex AMPL JANU EXECUTE 
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EXAMPLE macro program for BATCH 
SDF.LETE EXAMPL.OBJ+EXAMPL.SAV + EXAMPL.MAC 


$MESSAGE print a DIRECTORY 

SOIRECTORY OKsEXAMRL,* 


9-MAY-75 

EXAMPl.BAT 2 28-APR-75 

EXAMPl.CTL 3 9-HAY-75 

2 FILES, 5 BLOCKS 
1436 FREE BLOCKS 

SMESSAGE end OF the example batch stream 


SEOJ 


12.5 RT-11 MODE 

RT-11 mode provides the capability to enter commands to the RT-11 
monitor or to system programs and to create BATCH programs. RT-11 
mode may be entered with either the $JOB/RTll command or the $RTll 
command. If entered with the $JOB/RTll command, RTll mode remains in 
effect until the next $JOB command is encountered in the BATCH stream. 
If entered with the $RT11 command, RT-11 mode is in effect until a $ 
is encountered in the first position of the command line. 

The characters ., $, *, and tab or space appearing in the first 
position of a line (or card column 1) are interpreted as control 
characters and indicate the following: 

. command to the RT-11 monitor, e.g., 

. R PIP 

* data line; any line not intended to go to the RT-11 

monitor or to the BATCH run-time handler, e.g., a 
command to the RT-11 PIP program: 

*F I LEI. DflT/D 


NOTE 

The * is not passed as data to the program. 
Comment lines (!) cannot appear on data lines 
as they would be considered as data. 


$ BATCH command. Causes exit from RT-11 mode if RT-11 

mode was entered with the $RTll command. For 
example: 

<f RT5 :i ! ENTER R7-15. MODE 

. R PIP 

*BTB : FILES. DfiT/'D 

^DIRECTORY DT0: !LL-fiVE RT-rii MODE 

space/tab separator to indicate line directed to BATCH run-time 
handler. This separator is indicated by a in the 
following descriptions. 
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12.5.1 Running RT-11 System Programs 

The most common use of RT-11 mode is to send commands to the RT-11 
monitor and to system programs. For example, the following commands 
can be inserted in the BATCH stream to run PIP and save backup copies 
of files on DECtape. 

SRT11 
. R PIP 

*DT1 + = *. FOR/X 

The user must anticipate and include in the BATCH input stream 
responses that are required by the called program, e.g., the Y 
response to PIP's ARE YOU SURE? query. 

BATCH standard commands cannot be mixed with RT-11 mode data lines 
(i.e., lines beginning with an asterisk). For example, the proper way 
to do a $MOUNT within a sequence of RT-11 mode data commands is: 

*JQB/RT11 
. R M fi C R 0 
*fil=fii 

* fi 2 = fi 2 

AMOUNT D T 8:/P H V SIC fi L 
. R MfiCRO 

* S' 1 = D T : B1 

•* 8 2 = D 7 : B 2 


12.5.2 Creating RT-11 Mode BATCH Programs 

RT-11 mode may be used by advanced system programmers to create BATCH 
programs. These BATCH programs consist of standard RT-11 mode 
commands (monitor commands, data lines for input to system programs, 
etc.) plus special RT-11 mode commands. These special commands are 
interpreted by the BATCH run-time handler to allow dynamic 
calculations and conditional execution of the RT-11 mode standard 
commands. The following facilities allow the user to create BATCH 
programs and to dynamically control the execution of these programs at 
run-time. 


A. Labels 

B. Variable modification 

1) equating a variable to a constant or character (LET 
statement) 

2) incrementing the value of a variable by 1 

3) reading a value into a variable 

4) conditional transfers on comparison of variable values 
with numeric or character values (IF and GOTO statements) 

C. Commands to control terminal I/O 

D. Other Control Characters 

E. Comments 


12.5.2.1 Labels — Labels in RT-11 mode are user-defined symbols that 
provide a symbolic means of referring to a specific location within a 
BATCH program. If present, a label must begin in the first character 
position, must be unique within the first six characters, and must 
terminate with a colon (:) and a carriage return/line feed 
combination. 
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12.5.2.2 Variables — A variable in RT-11 mode is a symbol 
representing a value that can change during program execution. The 26 
variables permitted in a BATCH program have the names A-Z? each 
variable requires one byte of physical storage. The user may assign 
values to variables in a LET statement. These values may then be 
tested by an IF statement to control the direction of program 
execution. 

Variables may be assigned values with a LET statement of the following 
form: 


HlET x = "c 

where x is a variable name A-Z and "c indicates the ASCII value of a 
character. For example: 

-*| LET A="0 

indicates that the value of variable A is equal to the 7-bit ASCII 
value of the character 0 (60) . 

The LET statement can also specify an octal value in the form: 

-|LET A=n 

where n is an 8-bit signed octal value in the range 0 to 377? 
positive numbers range from 0 to 177 and negative numbers from 200 to 
377 (-200 to -1) . 

Variables may be used to introduce control characters, such as 
ALTMODE, into a BATCH stream. For example, wherever 'A 1 appears in 
the following BATCH stream, BATCH substitutes the contents of variable 
A (the code for an ALTMODE): 

$ J 0 G / R T11 

LET ft = 22 

!fi IS ftN flLTMODE 

.R EDIT 

*EBF I LE. MftC" ft y ' ft' 

!ED IT FILE TO CHANGE THE VERSION NUMBER TO 2 
*GVERSI0N=' ft'’ D I 2' ft' '* ft' 

♦ EX' A'ft' 

*E0J 

The value of a variable can be incremented by 1 by placing a percent 
sign (%) before the variable. For example: 

H %A 

indicates that the unsigned contents of variable A are to be increased 
by 1. 

Conditional transfers of control according to the value of a variable 
are indicated with an IF statement. The IF statement has the form: 

“•) IF (x — "c) labell, label2, label3 

or 

-^IF(x-n) labell, label2, label3 

where x is the variable to be tested, "c is the ASCII value to be 
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compared with the contents of the variable, or n is an octal value in 

labell"included 3 in'the d BftTCH 1 striaS? 12 ' “* "» »«• 

run-time C handler U tcansfecs control^o? ^ ° r (x "»' the BMC " 

• labell if the value of the expression is less than zero. 

• label2 if the value of the expression is equal to zero. 

• label3 if the value of the expression is greater than zero. 

If one of th e labels is omitted, and the condition is met for the 
statement ' C ° ntr01 transfers to line following the IF 


NOTE 

Since this comparison is a signed byte 
comparison, 377 is considered to be -1. 


The characters + and - allow the user to control where BATCH beqins 
searching for labell, label2, and label3. If the label is preceded by 
a minus sign (-) , the label search starts just after the $JOB command. 
It a plus sign (+) or no sign precedes the label, the label search 
starts after the IF statement. For example, the following statement: 

~HIF(B-"9) -LOOP, LOOP1, 

transfers program control to the label LOOP following the $JOB command 
it the contents of variable B are less than the ASCII value of 9 or to 
the label LOOP1 following the IF statement if B is equal to ASCII 9. 
If the contents of variable B are greater than the ASCII value of 9 ! 
program control goes to the next BATCH statement in sequence. 

The GOTO statement unconditionally transfers program control to a 
label specified as the argument of the statement. This statement may 
be one of the following three forms: 

HgOTO label transfers control to the first occurrence of label 

that appears after this GOTO statement in the 
BATCH stream, 
same as GOTO label. 

transfers control to the first occurrence of label 
that appears after the $JOB command. 

If the label is not found, transfer goes to $EOJ. 

Jext f °lihM n rmp T ?f S c at K inen 1 t transfers control unconditionally to the 
?® xt b00p lf such a label appears in the BATCH stream following 

the GOTO statement. ^ 


-*| GOTO +label 
-\ GOTO -label 


-»| GOTO LOOP 
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NOTE 

If a label cannot be found, e.g., a 
minus sign was intended but omitted, the 
BATCH handler searches until the end of 
the CTL file is reached and ends the 
job. 


12.5.2.3 Terminal I/O Control — Commands may be issued directly to 
the BATCH run-time handler to control console terminal input/output to 
the log file. If none of the following commands is entered, TTYOUT is 
assumed. 


^ NOTTY 

-*| TTYIN 
—|TTYIO 
H TTYOUT 


do not write terminal input/output to the 
Comments to the log will still be logged. 

write only terminal input to the log file. 

write terminal input and output to the log 

write only terminal output to the log file 


log file. 


file. 

(default). 


12.5.2.4 Other Control Characters — Other control characters allowed 
in an RT-11 mode command that begins with a period (.) or an asterisk 
(*) indicate the following: 

'text' command to BATCH run-time handler, where text can be 

one of the following: 

accept input from the console terminal; 
notify the operator that action is 
required by ringing a bell and printing 
a ?. 

output current log buffer, 
insert a new line (line feed) in the 
BATCH stream. 

insert contents of variable where x is 
an alphanumeric variable A-Z, indicates 
that the contents of the variable are to 
be inserted as an ASCII character at 
this place in the command string, 
direct the message to the console 
terminal. 

Example 1: 

The following commands allow the operator to enter the name of a MACRO 
program to be assembled. The BATCH stream contains: 

SJ0B/RT11 
. R MACRO 

*'• "ENTER MACRO COMMAND STRING"' ' CTY' 

$ EG J 

The operator receives the following message at the terminal; he types 
a response, followed by carriage return, and BATCH processing 
continues. 


CTY 


FF 

NL 


"message’ 
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ENTER MACRO COMMAND STRING?FILE;FILE=FILE 


Example 2: 

The user may want to run the same BATCH file on several systems with 
configurations and would want to assign a device 
dynamically. The following RT—11 mode command allows the user to 
request that the listing device name be entered by the operator. 

•ASSIGN ' "PLEASE TYPE LST DEVICE NAME " '* ' C T V ' LSI 

The operator receives the message and responds with the device to be 
used as the listing device (DT2:). 

PLEASE TVPE LST DEVICE NAME?DT2: 


12.5.2.5 Comments — Comments 
separate comment statements, 
separator followed by a ! and 


can be included in RT-11 mode as 
This is accomplished by typing a 
the comment, e .g. , 


Hi OPERATOR ACTION IS REQUESTED IN THIS JOB. BE PREPARED. 


12.5.3 RT-11 Mode Examples 

The following are examples of BATCH programs using the RT-11 mode. 
Example Is 

This BATCH program assembles, lists, and maps 10 programs with only 12 
BATCH commands. 1 


SJOB/RTli !ASSEMBLE; LIST; MAP PROG© TO PROG 9 

TTVIO 

.'WRITE TERMINAL I/O TO THE LOG FILE 
LET N ="0 
! START AT PROG0 

LOOP : 

.R MACRO 

*PR0G•' N'; LOG: /C = P R 0 G' N'* /N: TTM 

.R LINK 

*> L0G : = PR0G ' N f 

y. n 

! INCREMENT VARIABLE N 
IF<N- n 9)-L00P;-LOOP;END 
! TEST FOR END 

END : 

SEOJ 


Example 2: 

The following program allows the user to set up a master control 
stream to run several BATCH jobs with one call to BATCH. First the 
user sets up a BATCH job (INIT.BAT) that will $CHAIN to the master 
control stream: 
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SJ0B/RT11 

LET I = 11 0 

•INITIALIZE INDEX 
$CHA IN MASTER !GO TO MASTER 
4EOJ 

The following is the master control stream (MASTER.BAT) to which INIT 
chains. 

$J0B/RT11 !MASTER CONTROL STREAM 

YA 

.'BUMP INDEX BV 1 
IF<I-"7)##END 

.R BATCH 

•THIS IS A $CHAIN 

*JOB" l y 

!RUNS J0B1-J0B7 

END : 

^MESSAGE END OF BATCH RUN 
SEQJ 

Each job to be run by MASTER.BAT must contain the following: 

$ JOB 

!BATCH COMMANDS 
$CHAIN MASTER 
$EOJ 

The master control stream is activated by calling BATCH as follows: 

.R BATCH 
* INIT 


12.6 CREATING BATCH PROGRAMS ON PUNCHED CARDS 

To create a BATCH program on punched cards, the user punches into the 
cards the commands as described in Section 12.4. Each command line 
occupies a single punched card. Only one card, the EOF card, is 
different from the standard BATCH commands. The EOF (end-of-file) 
card terminates the list of jobs from the card reader. 

To create the EOF card, hold the MULT PCH key on the keypunch keyboard 
while typing the following characters (DEC029 codes, see Appendix H 
for DEC026 codes):. 

-&016789 

This procedure produces an EOF card with holes punched in the first 
column (see Figure 12-1). 
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Figure 12-1 EOF Card 


12.6.1 Terminating BATCH Jobs on Cards 

To terminate BATCH, type \F, followed by a carriage return, put two 
EOF cards and a blank card in the reader, and ensure that the card 
reader is ready. Note that a small card deck (less than 512 
characters) may require more than two EOF cards to terminate the deck. 


12.7 OPERATING PROCEDURES 


12.7.1 Loading BATCH 

After the RT-11 system has been bootstrapped and the date and time 
entered, the BATCH run-time handler must be made resident by typing 
the RT-11 LOAD command as follows: 

.LORD Bft 

The BATCH run-time handler must be detached with the /U switch to the 
BATCH compiler command line (see Section 12.7.2) before it is removed 
with the RT-11 command UNLOAD. 

Unless the log device is SY: or any device for which the handler is 
already resident, the BATCH log device must be made resident. The log 
device is loaded by typing: 

.LOAD log 

where log is the device to which the BATCH log is to be written, e.g.. 
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. LOAD LF* 


The loading of device handlers can, of course, be done with a single 
LOAD command, e.g., 

. LORD BA, LF' 

The log device must then be assigned the logical device name LOG. 
This is accomplished with the RT-11 monitor command ASSIGN in the 
form: 


.ASSIGN log:LOG 

For example, if LP: is the log device, type: 

.ASSIGN LP:LOG 

The device to be used for listing files must be made resident with the 
LOAD command and then assigned the logical device name LST:. This is 
accomplished with the RT-11 ASSIGN command in the form: 

.ASSIGN 1isdev:LST 

where lisdev is the physical device to be used for listings. If, for 
example, listings are to be produced on the line printer, type: 

. ASSIGN LP :LST 


NOTE 

The ASSIGN command with no arguments 
should not be used in a BATCH program 
since it would then deassign the log 
and list devices, possibly causing the 
BATCH job to terminate. 


The BATCH Run-Time Handler input device (Compiler output device) must 
also be made resident. If this device is already resident or is SY:, 
it need not be loaded. For example, to load the DECtape handler as 
the input device, type: 


. LOAD DT 


If the input file to the BATCH Compiler is on cards, the card reader 
handler must be loaded by typing: 

.LOAD CR 


NOTE 


If input is on cards, the RT-11 monitor 
command SET must be used (before the 
handler is loaded) to specify CRLF and 
NOIMAGE modes, i.e., 

.SET CR CRLF 

to append a carriage return/line feed 
combination to each card image, and 

.SET CR NO I MAGE 

to translate the card by packing card 
code into ASCII data, one column per 
byte. 
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12.7.2 Running BATCH 

When all necessary handlers have been loaded , the BATCH Compiler is 
run as follows: 

.R BATCH 

BATCH responds by printing an asterisk (*) to indicate readiness to 
accept command string input. In response to the *, type the output 
file specifications for the control file followed by an equal sign or 
left angle bracket/ followed by the input file specifications for the 
BATCH file as follows: 

{{spcO}{/Spcl}{/switch}=}spc3{/...}{ f spc8/switch} 


where: 

spcO 

is the BATCH compiler output device and file to be 
used by the BATCH run-time handler. The device 
specified must be random-access. This file should 
not be deleted or moved by the job that is within 
it; nor should the system ever be compressed from 
within a batch job. If spcO is omitted/ a file is 
generated on the default device (DK:) with the same 
name as the first input file but with a .CTL ex¬ 
tension. If no extension is specified/ .CTL is 
assumed. 

spcl 

is the log file created by the BATCH run-time 
handler. If no log device is specified/ LOG: is 
assumed. The device name specified for spcl must be 
that assigned to LOG:. 

The size of a log file on a file-structured device 
may be changed from the default size of 64 (decimal) 
by enclosing the requested size in square brackets. 
For example: 

* zFILE.LOG[10]=FILE 

The default extension for spcl is .LOG. 

spc3-spc8 

are input file specifications. If no input 
extensions are specified/ the default extension is 
.BAT. If a .CTL file is specified/ a precompiled 
file is assumed and it must be the only file in the 
input list. 

/switch 

is one or more of the following: 

/N compiles but does not execute; creates 

BATCH control file (.CTL ), generates an 
ABORT JOB message at the beginning of 
the log file , and returns to RT-11 
monitor. 

/T:n if n=0 , sets the /NOTIME switch as 

default on the $JOB command; if n=l/ 
the default switch on the $JOB command 
is /TIME. 
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/U indicates that BATCH compiler is to 

detach the BATCH run-time handler from 
the RT-11 monitor for subsequent 
removal. The prompting message !UNLOAD 
BA! is printed. 


NOTE 

The RT-11 monitor command UNLOAD 
BA must be specified to actually 
remove the handler. The handler 
must be reloaded before BATCH is 
run again. 


/V prints version number of BATCH compiler 

/X indicates that input is a precompiled 

BATCH program (used when .CTL is not 
the extension or when the extension is 
omitted). 


Example Is 

In the following example, the user calls BATCH to compile and execute 
the three input files (PROGl.BAT, PROG2.BAT, PROG3.BAT), to gen¬ 
erate on DK: the compiler output files and to generate on LOG: a log file. 

.R BATCH 

+PR0G1. BAT, PR0G2. BAT, PRO63. BAT 


Example 2: 

The following commands compile and run SYBILD.BAT, printing the 
version number of BATCH. 

.R BATCH 
* S V BIL D / V 
BATCH V01-62 


Example 3: 

The following commands compile PROTO.BAT to create PROTO.CTL but do 
not run the compiled program. 

. R BATCH 
* P ROT0/N 


Example 4: 

Type the following commands to unlink BA.SYS from the monitor and to 
unload it. 


.R BATCH 
*/U 

! UNLOAD BA! 
. UNLOAD BA 


January 1976 


12-48 




BATCH 


Example 5: 

The following commands compile FILE.BAT from magtape to create 
FILE.CTL on DK1:, execute the compiled file, and create a log file 
named FILE.LOG of size 20 on LOG:. 

. R BATCH 

*DK1. FILE, FILEE 203»MT. FILE 


Example 6: 

The following commands execute a precompiled job called FILE.TST. 

. R BATCH 

♦ FILE. TST/X 

Example 7: 

The following commands execute a precompiled job called FILE.CTL. 

. R BATCH 
♦FILE/X 

Example 8: 

The following commands accept input from the card reader to create on 
DK: a file called TEMP.CTL and execute that file. 

. R BATCH 

♦ CR : 


Example 9: 

The following commands accept input from the card reader to create on 
DK: a file called JOB.CTL and execute that file. 

. R BATCH 
♦JOB-CR: 


12.7.3 Communicating with BATCH Jobs 

During the execution of a BATCH stream, the operator may be requested 
to supply action or provide information or to insert a command line 
into the BATCH stream. The operator can accomplish this by typing 
directives to the BATCH handler via the console terminal. 


NOTE 

These directives are equivalent to the 
compiler output generated by BATCH in 
the .CTL file. The .CTL file is an 
ASCII file that can be listed using PIP. 


These 


where 


directives have the form: 

\dir 

dir is one of the directives listed 


in Table 12-6. 


I 


12-49 


January 1976 






BATCH 


To use these directives, the operator must get control of the BATCH 
run-time handler by typing a carriage return on the console terminal. 
When BATCH executes a command, it notices the carriage return and 
prints a carriage return/line feed combination at the terminal. The 
directives in Table 12-6 may then be entered by the operator; those 
most useful to the operator are marked with an asterisk (*) . 


Table 12-6 

Operator Directives to BATCH Run-Time Handler 


Directive 

Explanation 

\@ 

Send the characters that follow to the console 

terminal. 

*\A 

Change the input source to be the console terminal. 

*\B 

Change the input source to be the BATCH stream. 

*\c 

Send the following characters to the log device. 

*\D 

Consider the following characters as user data. 

*\E 

Send the following characters to the RT-11 monitor. 

*\F 

Force the output of the current log block. If this 
directive is followed by any characters other than 
another BATCH backslash (\) directive, the BATCH job 
prints an error message and terminates? control 
returns to the RT-11 monitor. 

\G 

Get characters from the console terminal until a 
carriage return is encountered. 

\Hn 

Help function to change the logging mode where n 
specifies the following: 


0 Log only .TTYOUT and .PRINT. 

1 Log .TTYOUT, .PRINT, and .TTYIN 

2 Do not log .TTYOUT, .PRINT, and .TTYIN 

3 Log only .TTYIN 

\Ivxlabell?label2?label3? 

IF statement which causes conditional transfer, where v 
is a variable name in the range A-Z; x is a value for 
the signed 8-bit comparison (v-x); and labell, label2, 
label3 are 6-character labels to which control is 
transferred under certain conditions. (All labels must 
be six characters in length; if too short, pad with 
spaces.) If v-x is less than 0, control transfers to 
labell? if v-x is equal to 0, control goes to label2; 
if v-x is greater than 0, control goes to label3. The 
direction for the label search is indicated by ?? if ? 
is 0, the search begins at the beginning of this job? 
if ? is 1, the label search begins after the IF 
statement. 


(continued on next page) 
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Table 12-6 (cont.) 

Operator Directives to BATCH Run-Time Handler 


Directive 

Explanation 


\Jlabel? 

Jump, unconditional transfer; where label is 

6-character label and ? is 0 or 1. (All labels 
be six characters in length; if too short, pad 
spaces.) If ?=0, label is a backward reference; 
?=1, label is a forward reference. 

a 

must 

with 

if 

\KvO 

Increment variable v where v is a variable name in 
range A-Z. 

the 

\Kvln 

Store the 8-bit number n in variable v. 


\Kv2 

Take the value in variable v and return it to 
program (via .TTYIN). 

the 

\Llabel 

Insert label as a 6-character alphanumeric string in 
the BATCH stream. (All labels must be six characters 
in length; if too short, pad with spaces.) Labels must 
not include backslash characters. Characters beyond 
six are ignored. 


Example 1: 

The operator may wish to interrupt the BATCH handler to enter 
information from the console as a result of a /WAIT or 1 CTY 1 in the 
BATCH stream. For example, the following message appears at the 
terminal. 


$ M E 5 S ft G E/WRIT WRITE NECESSRRV FILES TO DISK 

To divert BATCH stream input from the current file to the console 
terminal, the operator types a \E and can then enter commands to the 
RT-11 monitor until he types a \B. Control then returns to the BATCH 
stream. For example, to respond to the preceding message, the 
operator types: 


WRITE MECE.SSARV ‘FILES TO DISK 
7SRSER PIP 
PIP 

\ER PIP 

SDRK +-DT2 :FILE. MRC/X 
\E\F\B 


changes input source to TT: 
and calls the RT-11 monitor to 
run PIP 

writes FILE.MAC from DT2: to 

RK: 

outputs log block and returns 
control to the BATCH stream 


Example 2: 

The following BATCH program allows the user to make frequent edits to 
a file and list only the edits. First the user creates a BATCH 
program which will assemble with a listing and link the file. This 
BATCH program, called COMPIL.BAT, contains: 


SJGB/RTll 

TTVIO 

! WRITE TERMINAL I/O TO THE LOG FILE 

.R MACRO 
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!CALL THE MACRO ASSEMBLER 
*FILE,FILE/C=F ILE 

$ME5SAGE/WAIT OK TO TVF'E EDIT COMMANDS 
.R LINK 

!CALL THE RT-11 LINKER 
♦ FILE,LOG : =FILE 
$EOJ 


At run-time, the user can insert commands into the BATCH stream via 
the console terminal. These commands will search for the section of 
the listing file that has been edited and then list this section to 
the log. The command must be inserted after the R MACRO command but 
before the R LINK command. The operator types the following to use 
COMPIL.BAT. 


.LOAD BA,L P 
.ASSIGN LP: LOG 
.R BATCH 
* C 0 N PIL 

OK TO TYPE EDIT COMMANDS 

? S A \ E 

SER EDIT 

*E*RFILE. l.ST$$ find FILE.LST on system device 
*EMF1LE. LST$$ 

*PBEl.L : $ = * find BELL, move pointer back 


print contents of buffer to log and console 
print remainder of input file to log 
return to BATCH 



END BATCH 


12.7.4 Terminating BATCH 

When BATCH terminates normally, it prints: 


END BATCH 


and returns control to the RT-11 monitor. 

To abort BATCH while it is executing a BATCH stream, the best method 
is to interrupt the BATCH handler by typing a carriage return. When 
BATCH executes the next command after the carriage return was typed, 
it prints a carriage return/line feed combination at the console 
terminal and the operator has control. The operator then types \F 
followed by a carriage return. The BATCH handler responds with the FE 
(forced exit) error message and writes the remainder of the log 
buffer. Control returns to the RT-11 monitor. 

CTRL C can be typed to terminate BATCH but is a more drastic method 
than that described above. CTRL C should be used when BATCH is in a 
loop or when a long assembly is running. 


12.8 DIFFERENCES BETWEEN RT-11 BATCH AND RSX-llD BATCH 

For those users who may wish to run their RT-11 BATCH programs under 
I RSX-llD, or vice versa. Table 12-7 lists the differences between the 
two programs. A user who plans to run his BATCH programs under both 
systems should ensure that the programs are compatible with both RT-11 
and RSX-llD BATCH. 
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Table 12-7 

Differences Between RT-11 and RSX-11D BATCH 


Differing Aspects 

RT-11 

RSX-11D 

File descriptors 

dev:filnam.ext/sw 

SY:filnam.ext/sw 

Default listing extension 

.LST(or .LIS) 

• LIS 

Executable file extension 

.SAV 

.EXE 

Incompatible commands 

$BASIC 

$CALL 

$CHAIN 

$LIBRARY 

$RT11 

$SEQUENCE 

$MCR 

Incompatible switches 

$COPY/DELETE 

$CREATE/DOLLARS 

$CREATE/LIST 

$DATA/DOLLARS 

$DATA/LIST 



$DIR file/LIST 
$DISMOUNT/WAIT 

$DIR file/DIRECTORY 


$DISMOUNT lun:/LOGICAL 
$FORTRAN/DOLLARS 
$FORTRAN/MAP 


$JOB/BANNER 

$JOB/NAME 


$JOB/LIST 

$JOB/LIMIT 


$J0B/RT11 
$JOB/TIME 
$JOB/UNIQUE 

$JOB/MCR 


$LINK/LIBRARY 

$LINK/OBJECT 

§MACRO/CREF 

$MACRO/DOLLARS 

$MACRO/LIBRARY 

$MACRO/MAP 

$MESSAGE/WAIT 

$MESSAGE/WRITE 

$PRINT/DELETE 

$LINK/MCR 

$DATA input 

appears as if from 

appears as if from 


input 

a file named 

FOR001.DAT 

Logical device names 

in $MOUNT and 

logical unit numbers 


$DISMOUNT 

only 

$RUN 

file name must be 

RSX11DBAT.EXE is 


specified 

default 


12.9 ERROR MESSAGES 

Two types of errors are reported by the BATCH system: user BATCH 
stream errors found by the compiler and noted in the BATCh log file, 
and system or operator errors noted at the console at run-time. Note 
that when BATCH is called from within a BATCH stream, both types of 
error messages are sent to the log. 
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The following messages detail errors found by the compiler and 
in the log file. An error is indicated by the printing 
erroneous line, an uparrow (or circumflex) under the error, an 
the following messages. 


noted 
of the 
one of 


Message 
ABORT JOB 

BAD CONSTRUCTION 

BAD SEQUENCE ARGUMENT 

BAD VARIABLE 

BAD VID 

BATCH HANDLER NOT RESIDENT 

BATCH STACK OVERFLOW 
CC 'MAND NOT UNIQUE 

DISMOUNT ERROR 

MISSING 

ILLEGAL '+' 

ILLEGAL CHARACTER 


Meaning 

An error has occurred in compiling 
a BATCH program; the compiler 
forces the job to abort. All error 
messages are printed in the log 
f ile. 

In RT-11 mode, an IF statement is 
not in the correct form or there 
was an illegal 'text' directive. 

The identification number specified 
in a $SEQUENCE command is not 
numeric. 

The variable specified is not one 
of the characters A-Z. 

The volume identification specified 
in a $MOUNT command is not in the 
correct form, e.g.» the equal sign 
(=) or the text is missing. 

The BATCH run-time handler was not 
loaded with the RT-11 LOAD command 
(see Section 12,7,1). 

There are too many nested $CALL 
commands in the BATCH stream. 

The spelling of a command is not 
unique (appears only when 
$JOB/UNIQUE was specified). 

The logical device name specified 
does not exist. 

A $ is not present in the first 
position of the command line (or 
card column 1). 

The + construction was used when 
not allowed (e.g., in a $RUN or 
$BASIC input file descriptor), 
there is a + in an output file 
descriptor, or a + terminates a 
control statement. 

The character specified is not used 
in proper context. 


(continued on next page) 
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Message 

ILLEGAL SWITCH 

ILLEGAL SWITCH COMBINATION 

LINE TOO LONG 

MULTIPLE SWITCH 
NO $EOJ 

NO FILE 

NO FILE NAME BEFORE 
NO LOGICAL DEVICE 


Meaning 

The switch name specified is not a 
legal RT-11 BATCH switch or is not 
legal for this field. 

More than one switch of the same 
type, e.g., /INPUT and /SOURCE 
exists on same command line. 

The input line entered is greater 

than 80 characters. 

The same switch is specified more 
than once in a single command line. 

A $JOB or $SEQUENCE command appears 
without a preceding $EOJ to end the 
previous job. 

No file descriptor was found in the 
BATCH stream where one was 

expected, or no file name was 

entered in the $CREATE command. 

An extension was specified but no 
file name preceded it. 

No logical device is specified in a 
$MOUNT command. 


NO PHYSICAL DEVICE 


No physical device is specified in 
a $MOUNT command. 


PLEASE ASSIGN LOG,LST 

PLEASE LOAD LOG HANDLER 

SEPARATOR MISSING 

SWITCH NOT UNIQUE 

TOO MANY FILE DESCRIPTORS 

UNKNOWN COMMAND 


The log device (LOG:) and/or the 
listing device (LST:) were not 
assigned (see Section 12.7.1). 

The log device handler is not 
resident (see Section 12.7.1). 

A file descriptor was not 
terminated by a space, a +, a , or 
a carriage return. 

The spelling of a switch is not 
unique (appears only when 
$JOB/UNIQUE is specified). 

More than six file descriptors are 
specified in a $command line. 

The command specified with a $ in 
character position 1 is not a legal 
BATCH command. 
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The following messages, generated by system or operator errors, are 
noted on the console at run-time. 


Message 

Meaning 

BAD COPY OF HANDLER 

The copy of BA.SYS in memory is 
bad. BATCH cannot be run until 

BA.SYS is unloaded and reloaded 
(see Section 12.7.1). 

BAD SWITCH 

The command line to the BATCH 
Compiler contains an illegal 
switch. 

BATCH FATAL ERROR 

A nonrecoverable error has occurred 
(e.g., the system device is 
WRITE-LOCKed); BATCH must be 
rerun. The system may have to be 
rebootstrapped. 

BATCH STACK OVERFLOW 

There are too many nested $CALL 
commands in the BATCH stream. 

BC 

Fatal error. A Bad Code was found 
in the control file by the BATCH 
handler. This can happen when a 
.CTL file has been garbled or if an 
editing mistake was made by the 
programmer when altering or 
creating the file with EDIT. 

END BATCH 

A BATCH job has been terminated. 

EOF WITH NO EOJ 

A file was not terminated with a 
$EOJ command. 

FE 

Fatal error. A Forced End occurred 
due to the appearance in the .CTL 
file of an illegal \F followed by a 
carriage return or BATCH was 
terminated from the console with a 
\F followed by a carriage return. 
The \F must be followed by another 
BATCH control directive. 

ILLEGAL COMMAND LINE 

Command line to the BATCH compiler 
is incorrect. 

ILLEGAL DEVICE 

A $DISMOUNT command was attempted 
on device that was not assigned. 

ILLEGAL LOG DEVICE 

Magtape, cassette, or a read-only 
device (e.g., PTRs) was specified 
as the log device. 

INPUT ERROR 

An error occurred while BATCH was 
attempting to read the compiler 
input file (.BAT). 


(continued on next page) 
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Meaning 

Message 

INPUT FILE? 

An input file descriptor was not 
specified to the BATCH compiler 
command line. 

10 

Fatal error. An Input or Output 
error occurred when the BATCH 
handler was attempting to read the 
.CTL file or write to the log file. 
The probable cause of this error is 
a log file overflow. 

LOG DEVICE ERROR 

An error • occurred on the log 

device. 

LU 

Fatal error. A Lock Up occurred in 
the BATCH handler because it could 
not find a free channel or a 
channel it could use. This can 
happen if all channels are opened 
for magtape or cassette operations 
within the BATCH stream. 

NO CONTROL FILE 

The .CTL file was probably sent to 
a nonfile-structured device (e.g., 
LP:) without using the /N switch to 
inhibit execution. 

OUTPUT DEVICE FULL 

The temporary file (.CTL) created 
by BATCH is too large for the 
specified device. Try compressing 
the device with PIP, or use another 
device. 

OUTPUT ERROR 

An error occurred while BATCH was 
attempting to write the compiler 
output file (.CTL) or magtape or 
cassette was specified as the .CTL 
output device. 

OUTPUT FILE NOT OPEN 

Fatal error. BATCH attempted to 
write on a .CTL file without 
opening it. 

RETURN FROM CALL ERROR 

Fatal error. BATCH cannot read 
control file which called a 
subprogram. BATCH cannot resume 
execution on return from call. 

TOO MANY OUTPUT FILES 

A third output file was specified 
to the BATCH compiler; only two 
output files may be specified. 

!UNLOAD BA! 

Prompting message printed when /U 
switch is given to the compiler. 
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ASSEMBLY, LINK, AND BUILD INSTRUCTIONS 


The information that formerly appeared in this appendix has now been 
incorporated into the RT-11 System Gen e ration Manual , DEC-ll-ORGMA-A-D. 
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APPENDIX B 


COMMAND AND SWITCH SUMMARIES 


Command and switch summaries of the various RT-11 system and utility 
programs are grouped here for the user f s convenience. Refer to the 
appropriate chapter for details. 


B.l KEYBOARD MONITOR (Chapter 2) 


B,1,1 Command Summary 

Only those command characters underlined need be entered; all command 
lines are terminated by typing a carriage return. 


Command Format 


ASSIGN devsudev 


B location 


CLOSE 


DAT E dd-mmm-yy 


Used Under 


Explanation 


F/B,S/J Assigns a user-defined name (udev) as an 
alternate name for a device (dev)• 
Deassigns synonyms when used without any 
arguments• 

F/B # S/J Sets a relocation base (location ), which 
is an octal address to be used as a base 
address for subsequent Examine and 
Deposit commands. 


F/B,S/J Causes all currently open files to be- 
(B only) come permanent. 

F/B,S/J Enters the indicated day-month-year 
(dd-mmm-yy); this date is then assigned 
to newly created files, new device 
directory entries , and listing output. 
When used without an argument, the 
current date (as entered) is printed. 


D location = valuel # value2,..•,valuen 

F/B,S/J Deposits the specified values starting 
at the given location (location 

represents an octal address which is 
added to the base address to obtain the 
actual address at which values will be 
deposited). 
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Command Format Used Under Explanation 

E location m-location n Prints the contents of the specified 

F/B,S/J locations in octal on the console 

terminal (location represents an octal 
address which is added to the base 
address to obtain the actual address 
examined). 

FRUN dev:filnam.ext/N:n/S:n/P Initiates a foreground job which exists 

F/B on the device indicated (dev) under the 

(F only) specified filename and extension. /N:n 
is optionally used to allocate n 
(decimal) words over and above actual 
program size; /S:n is optionally used 
to allocate n words for stack space; /P 
is used for debugging purposes (the load 
address is printed but the program must 
be started using RSUME). 


GET dev:filnam.ext 

F/B,S/J 

Loads the specified memory image file 
(filnam.ext) into memory from the 
indicated device (dev:)• 

GT OFF 

F/B,S/J 

Used (after GT ON) to clear the display 
processor and resume printout on the 
console terminal. 

GT ON/L:n/T:n 

F/B,S/J 

Enables the display processor so that 
the display screen replaces the console 
as the terminal output device. /L:n may 
be optionally used to designate the 
number of lines to display (12" screen - 
l<=n<=37 octal; 17" screen - l<*n<*50 
octal)• /T:n may be optionally used to 
indicate the top position of the scroll 
display (12" screen - l<=n<=1350 octal; 
17" screen - l<=n<=1750 octal)• 

INITIALIZE 

F/B,S/J 
(B only) 

Resets background system tables; makes 
nonresident all handlers not loaded and 
purges background's I/O channels. 

LOAD dev,..• 

F/B,S/J 

Makes a device handler resident for use. 

LOAD dev=B,dev=F,•. 

F/B 

Makes a device handler resident for use 
with background and foreground jobs. 

R filnam.ext 

F/B,S/J 
(B only) 

Loads the specific memory image file 
(filnam.ext) into memory from the system 
device and starts execution. 

REENTER 

F/B,S/J 

Starts a program at its reentry address 
(i.e., its start address -2). 

RSUME 

F/B 

(F only) 

Resumes execution of a foreground 

program where it was suspended. 

RUN dev:filnam.ext 

F/B,S/J 
(B only) 

Loads the specified memory image file 
(filnam.ext) into memory from the 


indicated device (dev:) and starts 
execution. 


I 
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Command Format 


Used Under 


SAV E dev:filnam.ext areal,area2-arean 

F/B,S/J Writes the 
specified 
(filnam.ext) 
Memory is 
blocks. 


Explanation 


area(s) of user memory 
into the named file 
in save image format, 
transferred in 256-word 


SET dev:<NO>option=value 

{ } F/B,S/J 


START address 


SUSPEND 


TIME hh:mm:ss 


F/B,S/J 


F/B 

(F only) 
F/B,S/J 


UNLOAD dev,dev,... F/B,S/J 


Used to change device (dev:) handler 
characteristics and certain system 
configuration parameters. See Table 2-5 
(Section 2.7.2.8) for a list of options. 

Begins execution of the program 
currently in memory at the specified 
address. If an address is not 
indicated, the starting address in 
location 40 is used. 

Suspends execution of the foreground job 
currently running. 

Enters time of day in hours, minutes, 
seconds past midnight (hh:mm:ss). If all 
three arguments are omitted, the current 
time of day is output. 

Makes previously loaded handlers (dev) 
nonresident and frees the memory space 
they were using. 


B.1.2 Special Function Keys 


Key 

CTRL A 


CTRL B 


Used Under Function 


F/B,S/J Valid when the monitor GT ON command 
has been typed and the display is in 
use. Does not echo on the terminal. 
Used after CTRL S has been typed to 
effectively page output. 


F/B Echoes B> on the terminal and causes all 

keyboard input to be directed to the 
background job. At least one line of 
output will be taken from the background 
job (the foreground job has priority and 
control will revert to it if it has 
output). B> does not echo if output is 
already coming from the background job. 
(Control can be redirected to the 
foreground job via CTRL F.) 
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Key 

CTRL C 


CTRL E 


CTRL F 


CTRL 0 


CTRL Q 


CTRL S 


CTRL U 


CTRL Z 


Used Under Function 

F/B,S/J Echoes tC on the terminal, interrupts 
current program execution, and returns 
control to the Keyboard Monitor. If a 
program is waiting for terminal input or 
is using the device handler TT: for 

input, typing a single CTRL C interrupts 
execution and returns control to the 
monitor command level. Otherwise, two 
CTRL C's must be typed in order to 
interrupt execution. 

F/B,S/J Valid when the monitor GT ON command has 

been typed and the display is in use. 
Does not echo on the terminal, but 
causes all I/O to appear on both the 
display screen and the console terminal 
simultaneously. A second CTRL E 

disables console terminal output. 


F/B Echoes F> on the terminal and directs 

all keyboard input to the foreground job 
and all output to be taken from the 
foreground job. Control remains with 
the foreground job until redirected to 
the background job (via CTRL B) or until 
the foreground job terminates. 

F/B ,S/J Echoes to on the terminal and causes 
suppression of teleprinter output while 
continuing program execution. 

Teleprinter output is reenabled when one 
of the following occurs s 


1. A second CTRL 0 is typed 

2. A return to the monitor is 
indicated via CTRL C 

3. The running program issues a 

•RCTRLO directive (see 

Chapter 9) 

F/B,S/J Does not echo. Resumes printing 

characters on the terminal from the 

point at which printing was previously 
stopped (via CTRL S)• 

F/B,S/J Does not echo. Temporarily suspends 

output to the terminal until a CTRL Q is 
typed. If GT ON is in effect, each 
subsequent CTRL A causes output to 

proceed until the screen has been 
refilled once. 


F/B,S/J Echoes tU followed by a carriage return 
on the terminal and deletes the current 
input line. 

F/B,S/J Echoes tZ on the terminal and terminates 
input when used with the terminal device 
handler (TT:). 
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Key Used Under Function 

RUBOUT F/B,S/J Deletes the last character from the 

current line. Echoes a backslash plus 
the character deleted; each succeeding 
RUBOUT deletes and echoes another 
character; an enclosing backslash is 
printed when a key other than RUBOUT is 
typed. 


B.2 EDITOR (Chapter 3) 


B. 2.1 Command Arguments 

Format Meaning 

n A decimal integer (in the range -16383 to +16383) which may, 

except where noted, be preceded by a + or -. Whenever an 
argument is acceptable in a command, its absence implies an 
argument of 1. 

0 Refers to the beginning of the current line. 

/ Refers to the end of the text in the current Text Buffer. 

= Is used with the J, D and C commands only and represents -n, 

where n is equal to the length of the last text argument 
used. 


B.2.2 Input and Output Commands 


Command 


Form 


Meaning 


EDIT BACKUP 

EDIT READ 

EDIT WRITE 

END FILE 

EXIT 

LIST 


EB devjfilnam.ext[n]$ 

Opens a file for editing, creating a 
backup copy (.BAK). 

ER dev:filnam.ext$ 

Opens a file for input. 

EW devjfilnam.ext[n]$ 

Creates a new file for output. 

EF Closes the current output file without 

performing any further input/output 
operations. 

EX Outputs the remainder of the input file 

to the output file and returns control 
to the monitor. 

(-)nL Prints a specified number of lines on 

OL the console terminal. 

A 
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Command 

Form 

Meaning 

NEXT 

nN 

Outputs the contents of the Text Buffer 
to the output file, clears the buffer, 
and reads in the next page of the input 
file. 

READ 

R 

Reads a page of text from the input file 
and appends it to the contents of the 
buffer. 

VERIFY 

V 

Prints the current text line (the line 
containing the pointer) on the console 
terminal. 

WRITE 

(-)nW 

OW 

/W 

Outputs a specified number of lines of 
text from the Text Buffer to the output 
file. 


B.2.3 Pointer Relocation Commands 


Command 


Form 


Meaning 


ADVANCE 


(-)nA 

OA 

/A 


Moves the pointer over a specified 
number of lines in the Text Buffer. The 
pointer is positioned at the beginning 
of the line. 


BEGINNING B 


JUMP (-)nJ 

OJ 
/J 

=J 


Moves the current location pointer to 
the beginning of the Text Buffer. 

Moves the pointer over a specified 
number of characters in the Text Buffer. 


B.2.4 Search Commands 


Command 

Form 

Meaning 

FIND 

nFtext$ 

Beginning at the current location 
pointer, searches the entire text file 
for the nth occurrence of the specified 
character string. Pages of text are 
read into the Text Buffer, searched, and 



then written to the output file until 
the text string is found. 

GET 

nGtext$ 

Searches the contents of the Text 

Buffer, beginning at the current 



location pointer, for the next 

occurrence of the text string. 

POSITION 

nPtext$ 

Searches the input file for the nth 
occurrence of the text string; if the 
text string is not found, the buffer is 
cleared and a new page is read from the 


input file. 
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B.2.5 Text Modification Commands 


Command 

CHANGE 

DELETE 

EXCHANGE 

INSERT 


Form 

(-)nCtext$ 

0Ctext$ 

/Ctext$ 

(•) nD 
OD 
/D 
— D 


(-)nXtext$ 

0Xtext$ 

/Xtext$ 

Itext$ 


KILL 


(-)nK 

OK 

/K 


Meaning 

Replaces n characters, beginning at 
the pointer, with the indicated 
text string. 

Removes a specified number of 
characters from the Text Buffer, 
beginning at the current location 
pointer. 

Replaces n lines, beginning at the 
pointer, with the indicated text 
string. 

Inserts text immediately following the 
current location pointer; an ALTMODE 
terminates the text. 

Removes n lines from the Text Buffer 
beginning at the current location 
pointer. 


B.2.6 Utility Commands 

Command Form Meaning 


EDIT CONSOLE EC If scroller is in use, EC returns 

scroller to its normal mode (using full 
screen for display of text and 
commands); if scroller is not in use, 
EC clears screen and returns control to 
console terminal (following ED). 

EDIT DISPLAY ED If scroller is in use, ED recalls the 

text window (following EC) and arranges 
text and commands on screen; if 
scroller is not in use, ED displays 
text window only. 


EXECUTE MACRO nE 


Executes the command string specified 
in the last macro command. 


MACRO 


SAVE 


M/command string/ 

Inserts a command string into the Macro 
Buffer. 

OM Clears the Macro Buffer and reclaims 

M// the area for text. 

nS Copies the specified number of lines, 

beginning at the pointer, into the Save 
Buffer. 

U Inserts the entire contents of the Save 

Buffer into the Text Buffer at the 
position of the current location 
pointer. 
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Command 

Form 



Meaning 


EDIT 

VERSION 

EV 

Displays 

Editor 

the version number of 
on the console terminal. 

the 

EDIT 

LOWER 

EL 

Enables 

case. 

editing 

in upper- and 

lower- 

EDIT 

UPPER 

EU 

Returns editing 
(after EL). 

to upper-case 

only 


B.2.7 Immediate Mode Commands 


Command 
CTRL N 

CTRL G 

CTRL D 


Meaning 

Advances the pointer (cursor) to the 
beginning of the next line. 

Moves the pointer (cursor) to the 
beginning of the previous line. 

Moves the pointer (cursor) forward by 
one character. 


CTRL V 


RUBOUT 


ALTMODE (two) 

(one only) 

Any character other 
than the above (with 
the exception of CTRL C) 


Moves the pointer (cursor) back by one 
character. 

Deletes the character immediately 
preceding the pointer (cursor)• 

Enters Immediate Mode. 

Returns control to Editor Command Mode. 

Inserts the character as text positioned 
immediately before the pointer (cursor)• 


B.2.8 Key Commands 
Command 

ALTMODE 


CTRL C 


CTRL 0 


CTRL U 


Meaning 

Echoes $. A single ALTMODE terminates a 
text string. A double ALTMODE executes 
the command string. (When used alone on 
a line, two ALTMODES cause control to 
enter Immediate Mode, while a single 
ALTMODE returns control to Editor 
Command Mode.) 

Echoes at the terminal as tC and a 
carriage return. Terminates execution 
of EDIT commands, closes any open files, 
and returns to monitor command mode. 

Echoes to and a carriage return. 
Inhibits printing on the terminal until 
completion of the current command 
string. Typing a second CTRL 0 resumes 
output. 

Echoes tU and a carriage return. 
Deletes all the characters on the 
current terminal input line. 
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Command and Switch Summaries 


Command 

Meaning 

RUBOUT 

Deletes character from the current line. 

TAB 

Spaces to the next tab stop. Tab stops 
are positioned every eight spaces on the 
terminal. 

CTRL X 

Echoes tX and a carriage return. CTRL X 
causes the Editor to ignore the entire 
command string currently being entered. 
The Editor prints a <CRXLF> and an 
asterisk to indicate that the user may 
enter another command. 


B.3 PIP (Chapter 4) 
B.3.1 Switch Summary 


Switch 

Explanation 

/A 

Copies file(s) in ASCII mode; ignores nulls and 
rubouts; converts to 7-bit ASCII. 

/B 

Copies files in fqrmatted binary mode. 

/c 

Used in conjunction with another switch; causes 
only files with current date to be included in 
the specified operation. 

/D 

Deletes file(s) from specified device. 

/E 

Lists the device directory including unused 
spaces and their sizes. Sequence numbers are 
listed for cassettes. 

/F 

Pr i n ts a short directory (filenames only) of the 
specified device. 

/G 

Ignores any input errors which occur during a 
transfer and continues copying. 

/I or no 
switch 

Copies file(s) in image mode (byte by byte). 

/K 

Scans the specified device and types the absolute 
block numbers (in octal) of any bad blocks on the 
device. 

/I* 

Lists the directory of the specified device. 
Sequence numbers are listed for cassettes. 

/M:n 

Used when I/O transfers involve either cassette 
or magtape, n represents the numeric position of 
the file to be accessed in relation to the 
physical position of the cassette or magtape on 
the drive. 
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Switch 

/Nsn 

I /0 


/Q 


/R 

/s 


/T 

/U 

/V 

/W 


/X 

A 


/Z:n 


Explanation 

Used with /Z to specify the number of directory 
blocks (n) to allocate to the directory. 

Bootstraps the specified device (DTO, RKn, RF, 
DPn, DSn, DXn). 

Causes PIP to type each filename which is 
eligible for a wild card operation and to ask for 
a confirmation of its inclusion in the operation. 


Renames the specified file. 


Compresses the files on the specified directory 
device so that free blocks are combined into one 
area. 


Extends number of blocks allocated for a file. 


Copies the bootstrap from the specified file.into 
absolute blocks 0 and 2 of the specified device. 


Types the version number of the PIP program being 
used. 


Includes the absolute starting block and any 
extra directory words in the directory listing 
for each file on the device (numbers in octal). 
Used with /F, /L, or /E. 


Copies files individually (without 

concatenation). 


Causes system flies and .BAD files to be operated 
on by the command specified. 


Zeroes (initializes) the directory of the speci¬ 
fied device; n is used to allocate extra words 
per directory entry. When used with /N, the 
number of directory segments for entries may be 
specified. 


B.4 MACRO/CREF (Chapter 5) 

Refer to Appendix C for a complete summary of MACRO features, 
switches are also included in that appendix. 


CREF 
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Command and Switch Summaries 
B.5 LINKER (Chapter 6) 


B.5.1 Switch Summary 

The Linker switches (and the command line on which each must appear) 
are: 


Switch 

Name 

Command 

Line 

Meaning 

/A 

1st 

Alphabetizes the entries in the load map. 

/B:n 

1st 

Bottom address of program is indicated as n 
(illegal for foreground links). 

/c 

any 

Continues input files on another command line 
(must be used with /0). 

/F 

1st 

Indicates that the Linker will use the 

default FORTRAN library, FORLIB.OBJ. 

/I 

1st 

Includes the global symbols to be searched 
from the library. 

A 

1st 

Produces an output file in LDA format 

(illegal for foreground links). 

/M:n 

1st 

Allows terminal keyboard specification of the 
user's stack address. n represents an 
optional 6-digit unsigned octal number. 

/0:n 

any but 
the 1st 

Indicates that the program will be an over¬ 
lay structure; n specifies the overlay 
region to which the module is assigned. 

/R 

1st 

Produces output in REL format; only files in 
REL format will run in the foreground (REL 
format files may not be run under a 
Single-Job system). 

/s 

1st 

Allows the maximum amount of space in memory 
to be available for the Linker's symbol 
table. (This switch should only be used when 
a particular link stream causes a symbol 
table overflow.) 

/T or 
/T:n 

1st 

Transfer address is to be specified at 

terminal keyboard via n. 
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B.6 LIBRARIAN (Chapter 7) 


B.6.1 Switch Summary 

The Librarian (LIBR) switches (and the command line on which each must 
appear) are s 


Command 

Switch Line 


/C Any 


/D 1st 

/G 1st 


/R 1st 

/U 1st 


B.7 ODT (Chapter 8) 


B.7.1 Command Summary 

In the command format shown below, r represents a relocatable 
expression and n represents an octal number. 


Command 

Format 

Explanation 

RETURN 


Closes open location and accepts the next 
command. 

LINE 

FEED 


Closes current location and opens next 

sequential location. 

t or 

A 

t or A 

Opens previous location. 

*• or 

— 

+■ or_ 

Indexes the contents of the opened location 
by the contents of the PC and opens the 
resulting location. 

> 


> 

Uses the contents of the opened location as a 
relative branch instruction and opens the 
referenced location. 

< 


< 

Returns to sequence prior to last >, or «- 

command and opens the succeeding location. 

§ 


@ 

Uses the contents of the opened location as 


an absolute address and opens that location. 


Meaning 

The command is too long for the current line 
and is continued on the next line. 

Deletes modules from a library file. 

Global deletion; deletes entry points from 
the library directory. 

Replaces modules in a library file. 

Update; inserts and replaces modules in a 
library file. 
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Command 

/ 

\ 


G 

I 


Format 

/ 

r/ 

\ 

r\ 

1 

nl 


$n/ 

$B/ 

$C/ 

$F/ 

$P/ 

$R/ 

$S/ 

r;nA 

;B 

ryB 

rynB 

ynB 

r;C 

ryE 

yF 

ryG 

yl 

ryO 

yP 


Explanation 

Reopens the last opened location. 

Opens the word at location r. 

Reopens the last opened byte (SHIFT L). 

Opens the byte at location r. 

After a word or byte has been opened, prints 
the address of the opened location relative 
re J- ocati °n register n. If n is omitted, 
ODT selects the relocation register whose 
contents are closest to but less than or 
equal to the address of the opened location. 

Opens general register n (0-7). 

Opens the first word of the breakpoint table. 

Opens Constant Register. 

Opens Format Register. 

Opens Priority Register. 

Opens first Relocation Register (register 0). 
Opens Status Register. 

Starting at location r, prints n bytes in 
their ASCII formaty then inputs n bytes from 
the terminal starting at location r. 

Removes all Breakpoints. 

Sets Breakpoint at location r. 

Sets Breakpoint n at location r. 

Removes the nth Breakpoint. 


Prints the value of r and stores it in 
Constant Register. 


Searches for instructions that 
effective address r. 


the 
reference 


Fills memory words with contents of the 
Constant Register. 

Goes to location r and starts program. 

Fills memory bytes with the low-order 8 bits 
of the Constant Register. 


Calculates offset 
location to r. 


from currently open 


Proceeds with program execution from 
breakpoint. In single instruction mode only, 
executes next instruction. 
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Command 

Format 

k;P 

Explanation 

Proceeds with program execution from 
breakpoint; stops after encountering the 
breakpoint k times. In single instruction 
mode only, executes next k instructions. 

R 

;R 

Sets all Relocation Registers to -1 (highest 
address value)• 


;nR 

Sets Relocation Register n to -1. 


r;nR 

Sets Relocation Register n to the value of r. 
If n is omitted, it is assumed to be 0. 


R 

Selects the Relocation Register whose 
contents are closest to but less than or 
equal to contents of the opened location. 
Subtracts the contents of the register from 
the contents of the opened word and prints 
the result. 


nR 

Subtracts the contents of the Relocation 
Register n from the contents of the opened 
word and prints the result. 

S 

?s 

Disables single instruction mode; reenables 

breakpoints. 


;nS 

Enables single instruction mode (n can have 
any value and is not significant); disables 
breakpoints. 

W 

r;W 

Searches for words with bit patterns which 
match r. 

X 

X 

Performs a Radix 50 unpack of the binary 


contents of the current opened word? then 
permits the storage of a new Radix 50 binary 
number in the same location* 


B.8 PROGRAMMED REQUESTS (Chapter 9) 

Appendix E summaries the programmed requests available under RT-11, 
Version 2C. 


B. 9 BATCH (Chapter 12) 

Only those characters underlined need be entered. 

B.9.1 Switch Summary 
(Command Field) 

Switch Meaning 

Prints header of job on the log file. 


/BANN ER 

/CRE F 

/DELE TE 

January 1976 


Specifies that a cross reference listing is 
to be produced during compilation. 

Indicates that input is to be deleted after 
the operation is complete. 
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Command and Switch Summaries 


Switch Meaning 


/DOLLARS 

Indicates that the data following this com¬ 
mand may have an $ in the first character 
position of a line. Reading of the data is 
terminated by one of the following BATCH 
commands: 

$ JOB 

$SEQUENCE 

$EOD 

$EOJ 

or by a physical end-of-file on the BATCH 
input stream. 

/LIBRARY 

Includes the default library in the link 
operation. 

/LIST 

Produces a temporary listing on the listing 
device (LST:) or writes data images on the 
log device (LOG:). 

/MAP 

Produces a temporary linkage map on the list¬ 
ing device (LST:). 

/OBJECT 

Produces a temporary object file as output of 
compilation or assembly. 

/RT11 

Sets BATCH to operate in RT-11 mode. 

/RUN 

Causes linking (if necessary) and execution 
of programs compiled since the last link 
and go operation or start of job. 

/TIME 

Writes the time of day to the log file when 
commands are executed. 

/UNIQUE 

Checks for unique spelling of switches and 
keynames. 

/WAIT 

Pauses to wait for operator action. 

/WRITE 

Indicates that the operator is to WRITE- 
ENABLE a specified device or volume. 

/NOBANNER 

Does not print a job header. 

/NOCREF 

Does not create a cross reference listing. 

/NODELETE 

Does not delete input after operation is 
complete. 

/NODOLLARS 

Following data may not have a $ in the first 
character position; a $ in the first character 
position signifies a BATCH control command. 

/NOLIBRARY 

Does not include the default library in the 
link operation. 
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Command and Switch Summaries 


Switch Meaning 


/NOLIST 

Does not produce a listing. 

/NOMAP 

Does not create MAP file. 

/NOOBJECT 

Does not produce object file as output of 
compilation. 

/NORTH 

Does not set BATCH to operate in RT+11 
mode. 

/NORUN 

Does not execute or link and execute the 
program after performing the specified command 

/NOTIME 

Does not write time of day to log file. 

/NOUNIQUE 

Does not check for unique spelling. 

/NOWAIT 

Does not pause for operator action. 

/NOWRITE 

Indicates that no writes are allowed or that 
the volume specification is read-only; the 
operator is informed and must WRITE-LOCK the 
appropriate device. 


(Specification Field) 


/BASIC 

BASIC source file. 

/EXECUTABLE 

Indicates that runnable program image file 
is to be created as the result of a link 
operation. 

/FORTRAN 

FORTRAN source file. 

/INPUT 

Input file; default if no switches are 
specified. 

/LIBRARY 

Library file to be included in link operation 
(prior to default library). 

/LIST 

Listing file. 

/LOGICAL 

Indicates that the device is a logical device 
name. 

/MACRO 

MACRO or EXPAND source file. 

/MAP 

Linker map file. 

/OBJECT 

Object file (output of assembly or compila¬ 
tion) . 

/OUTPUT 

Output file. 

/PHYSICAL 

Indicates physical device name. 
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Command and Switch Summaries 


Switch Meaning 


/SOURCE 

Indicates source file. 

/VID 

Volume identification. 


B.9.2 Command Summary 


Command 

Meaning 

$BASIC 

Compiles a BASIC source program. 

$CALL 

Transfers control to another BATCH file, 
executes that BATCH file, and returns to the 
calling BATCH stream. 

$CHAIN 

Passes execution to another BATCH file. 

$COPY 

Copies files. 

$CREATE 

Creates new files from data included in 

BATCH stream. 

$DATA 

Indicates the start of data. 

$DELETE 

Deletes files. 

$DIRECTORY 

Provides a directory of the specified device 

$DISMOUNT 

Signals operator to dismount a volume from a 
device and deassigns a logical device name. 

$EOD 

Indicates the end of data. 

$EOJ 

Indicates the end of a job. 

$FORTRAN 

Compiles a FORTRAN source program. 

$ JOB 

Indicates the start of a job. 

$LIBRARY 

Specifies library that is to be used in 
linkage operations. 

$LINK 

Links modules for execution. 

$MACRO 

Assembles a MACRO source program. 

$MESSAGE 

Issues message to the operator. 

$MOUNT 

Signals operator to mount a volume on a 
device and optionally assigns a logical 
device name. 

$PRINT 

Prints files. 

$RT11 

Specifies that the following lines are RT-11 
mode commands. 
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Command 

$RUN 

$SEQUENCE 


Meaning 

Causes a program to execute. 

Assigns an arbitrary identification number 
to a job. 


B.10 DUMP (Appendix I) 
B.10.1 Switch Summary 


Switch 

Meaning 

/B 

Outputs octal bytes. 

/E:n 

Ends output at block n. 

/G 

Ignores input errors. 

/N 

Suppresses ASCII output. 

/0:n 

Outputs only block number n 

/S:n 

Starts output with block n. 

/w 

Outputs octal words. 

/X 

Outputs RAD50 characters. 


B.ll FILEX (Appendix J) 


B.ll.l Switch Summary 
Switch 

/A 


/D 


/F 


Meaning 

Indicates a character-by-character ASCII 
transfer in which rubouts and nulls are 
deleted; when /T is also used, each PDP-10 
is assumed to contain five 7—bit ASCII 

bytes. 

Deletes the named file from the device; 
valid only for DOS/BATCH and RSTS DECtape. 

Causes a "fast" listing of the device 
directory by listing filenames only. 
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Switch 


/I 


/I* 


/P 


/S 

/T 

/V 

/Z 


Meaning 


Performs an image mode transfer; ir the 

input is either DOS/BATCH, RSTS or RT-11, 

this is a word-for-word transfer; if the 

input is from DECsystem-10, /I indicates that 
the file resembles a file created on 

DECsystem-10 by MACY11, MACXll, or LNKXll 
with the /I switch: in this case, each 
DECsystem-10 36-bit word contains one PDP-11 
8-bit byte in its low-order bits. 

Causes a complete listing of the device 
directory, including filenames, block 
lengths, and creation dates. 

Performs a packed image transfer; if the 

input is from either DOS/BATCH, RSTS-11 or 
RT-11, this is a word-for-word transfer; if 
the input is from DECsystem-10, /P indicates 
that the file resembles a file created on 
DECsystem-10 by MACY11, MACXll, or LNKXll 
with the /P switch, in which case each 
DECsystem-10 36-bit word contains four PDP-11 
8-bit bytes aligned on bits 0, 8, 18, and 26. 
This mode is assumed if no mode switch (/A, 
/I) is indicated in a command line. 

Indicates the device is a DOS/BATCH (or 
RSTS) file-structured device. 

Indicates the device is a DECsystem-10 
file-structured device. 

Types out version number of FILEX. 

Zeroes the directory of the specified device 
in the proper format (valid only for 

DOS/BATCH and RSTS DECtape). 


B.12 SRCCOM (Appendix K) 


B.12.1 Switch Summary 


Switch 

Meaning 


/B 

Compares blank lines. Without this switch, 
blank lines are ignored. 


/c 

Ignores comments (all text on a line preceded 
by a semicolon) and spacing (spaces and 
tabs). 


/F 

Includes form feeds in the output file (form 
feeds are still compared if /F is not used. 



but they are not included in the output of 
differences). 

t 
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Summaries 

Command 

Meaning 

/H 

Types list of switches available (help text). 

/Lsn 

Specifies the number of lines that determine 
a match (where n is an octal number <=310). 
The default value for n is 3. 


/s 

Ignores spaces and tabs. 


B.13 PATCH (Appendix L) 


B.13.1 Command Summary 
Command 
/0 
/M 

Vr;nR 

b;B 

[s:]r,o/ 

[s:]r,o\ 

<CR> 

<LF> 

t or A 

@ 

F 

E 


Meaning 

Indicates overlay-structured file. 

Indicates monitor file. 

Sets relocation register n to value Vr. 

Sets bottom address of overlay file to b. 

Opens word location Vr + o in overlay segment 

s. 

Opens byte location Vr + o in overlay segment 
s. 

Closes currently open word/byte. 

Closes currently open word/byte and opens the 
next one. 

Closes the currently open word/byte and opens 
the previous one. 

Closes the currently open word and opens the 
word addressed by it. 

Begins patching a new file. 

Exits to RT-11 monitor. 
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B•14 PATCHO (Appendix M) 
® ^ • 1 Command Summary 


Command 

BYTE 

DEC 

DUMP 

EXIT 

HELP 


Format 


Meaning 


BYTE 


|#)name OF ( +) 

CSECT + OFFSET CSECT OR )-(OFFSET 
NAME ( )GLOBAL ( ) 

Modifies a given byte in an object module. 


Used when the proper checksum for the patch 
being made is unknown. PATCHO computes a 
checksum and prints out its value. 


♦DUMP 


Prints the contents of an object module in 
octal and causes an automatic POINT to the 
next module, if any, in the input file. 


♦EXIT 


Terminates the patch session by closing the 
file and returning control to the monitor. 


♦HELP 


Prints an explanation of the PATCHO commands. 


LIST 


OPEN 


♦LIST Lists the names of all object modules in the 
input file in the order in which they appear 
in the file. (A POINT command should be used 
after a LIST.) 

♦OPEN Opens files for input and output. 


POINT 


WORD 


♦POINT modnam 

Locates the specified object module (modnam) 
and prepares it for subsequent WORD, BYTE, or 
DUMP operations. 


#)name op (+ 

WORD CSECT + OFFSET =1%/CSECT OR ]-(OFFSET 
NAME ( )GLOBAL ( ) 

Modifies a given word in an object module. 


I 


B-21 









0 













APPENDIX C 


MACRO ASSEMBLER, INSTRUCTION, AND CHARACTER CODE SUMMARIES 


C.l ASCII CHARACTER SET 


Even 

Parity 

Bit 

7-Bit 

Octal 

Code 

Character 

0 

000 

NUL 

1 

001 

SOH 

1 

002 

STX 

0 

003 

ETX 

1 

004 

EOT 

0 

005 

ENQ 

0 

006 

ACK 

1 

007 

BEL 

1 

010 

BS 

0 

011 

HT 

0 

012 

LF 

1 

013 

VT 

0 

014 

FF 

1 

015 

CR 

1 

016 

SO 

0 

017 

SI 

1 

020 

DLE 

0 

021 

DC1 

0 

022 

DC2 

1 

023 

DC3 

0 

024 

DC4 

1 

025 

NAK 


Remarks 

Null, Tape Peed, CTRL SHIFT P. 

Start of Heading; also SOM (Start Of 
Message), CTRL A. 

Start of Text; also EOA (End Of Address), 
CTRL B. 

End of Text; also EOM (End Of Message), 
CTRL C. 

End of Transmission (END); Shuts off TWX 
machines, CTRL D. 

Enquiry (ENQRY); also WRU, CTRL E. 
Acknowledge; also RU, CTRL F. 

Rings the Bell. CTRL G. 

Backspace; also FEO, Format Effector. 

Backspaces some machines, CTRL H. 
Horizontal TAB. CTRL I. 

Line Feed or Line Space (New Line); 
Advances paper to next line; duplicated 
by CTRL J. 

Vertical TAB (VTAB). CTRL K. 

FORM FEED to top of next page (PAGE). 
CTRL L. 

Carriage Return to beginning of line. 

Duplicated by CTRL M. 

Shift Out; Changes ribbon color to red. 
CTRL N. 

Shift In; Changes ribbon color to black. 
CTRL 0. 

Data Link Escape. CTRL B (DCO). 

Device Control 1, turns transmitter 

(reader) on, CTRL Q (X ON). 

Device Control 2, turns punch or auxiliary 
on, CTRL R (TAPE, AUX ON). 

Device Control 3, turns transmitter 

(reader) off, CTRL S (X OFF). 

Device Control 4, turns punch or auxiliary 
Off, CTRL T (AUX OFF). 

Negative Acknowledge; also ERR, Error, 
CTRL U. 










MACRO Assembler, Instruction, and Character Code Summaries 


1 

026 

SYN 

0 

027 

ETB 

0 

030 

CAN 

1 

031 

EM 

1 

032 

SUB 

0 

033 

ESC 

1 

034 

FS 

0 

035 

GS 

0 

036 

RS 

1 

037 

US 

1 

040 

SP 

0 

041 

1 

0 

042 

n 

1 

043 

* 

0 

044 

$ 

1 

045 

% 

0 

046 

& 

0 

047 

t 

0 

050 

( 

0 

051 

) 

1 

052 

* 

0 

053 

+ 

1 

054 

9 

0 

055 

- 

0 

056 

* 

1 

057 

/ 

0 

060 

0 

1 

061 

1 

1 

062 

2 

0 

063 

3 

1 

064 

4 

0 

065 

5 

0 

066 

6 

1 

067 

7 

1 

070 

8 

0 

071 

9 

0 

072 

: 

1 

073 


0 

074 

< 

1 

075 

8 

1 

076 

> 

0 

077 

? 

1 

100 

@ 

0 

101 

A 

0 

102 

B 

1 

103 

C 

0 

104 

D 

1 

105 

E 

1 

106 

F 

0 

107 

G 

0 

110 

H 

1 

111 

I 

1 

112 

J 

0 

113 

K 

1 

114 

L 

0 

115 

M 

0 

116 

N 

1 

117 

O 

0 

120 

P 

1 

121 

Q 


Synchronous File (SYNC), CTRL V. 

End of Transmission Block) also 
Logical End of Medium, CTRL W. 
Cancel (CANCL), CTRL X. 

End of Medium, CTRL Y. 

Substitute, CTRL Z. 

Escape, CTRL SHIFT K. 

File Separator, CTRL SHIFT L. 

Group Separator, CTRL SHIFT M. 

Record Separator, CTRL SHIFT N. 

Unit Separator, CTRL SHIFT O. 

Space. 


Apostrophe or Acute Accent. 
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Instruction, and Character Code Summaries 


MACRO Assembler, 


1 122 R 

0 123 S 

1 124 T 

0 125 U 

0 126 V 

1 127 W 

1 130 X 

0 131 Y 

0 132 Z 

1 133 [ 

0 134 \ 

1 135 ] 

1 136 t 

0 137 «- 


0 


140 


\ 


SHIFT K. 

SHIFT L. 

SHIFT M. 

(Appears as A on some machines). 

(Appears as _ (Underscore) on some 

machines). 

Accent Grave. 




1 

1 

0 

1 

0 

0 

1 

1 

0 

0 

1 

0 

1 

1 

0 

1 

0 

0 

1 

0 

1 

1 

0 

0 

1 

1 

0 

1 

0 

0 


141 

a 

142 

b 

143 

c 

144 

d 

145 

e 

146 

f 

147 

g 

150 

h 

151 

i 

152 

j 

153 

k 

154 

1 

155 

m 

156 

n 

157 

o 

160 

P 

161 

q 

162 

r 

163 

s 

164 

t 

165 

u 

166 

V 

167 

w 

170 

X 

171 

y 

172 

z 

173 

{ 

174 

1 

175 

} 

176 

- 


1 177 DEL 


This Code Generated by ALTMODE. 

This Code Generated by PREFIX key (if 
Present) 

DELETE, RUBOUT. 


C.2 RADIX-50 CHARACTER SET 

Character ASCII Octal Equivalent 

space 40 

A-Z 101-132 


Radix-50 Equivalent 

0 

1-32 


? 
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$ 

44 

33 

• 

56 

34 

unused 


35 

0-9 

60-71 

36-47 

The maximum Radix-50 value is. 

thus: 



2 

47*50 +47*50+47=174777 

The following table provides a convenient means of translating between 
the ASCII character set and its Radix-50 equivalents. For example, 
given the ASCII string X2B, the Radix-50 equivalent is (arithmetic is 
performed in octal): 

X-113000 
2=002400 
B=000002 

X2B=115402 


Single Char, 
or 

First Char. 

A 003100 
B 006200 
C 011300 
D 014400 
E 017500 
F 022600 
G 025700 
H 031000 
I 034100 
J 037200 
K 042300 
L 045400 
M 050500 
N 053600 
O 056700 
P 062000 
Q 065100 
R 070200 
S 073300 
T 076400 
U 101500 

V 104600 
W 107700 
X 113000 

Y 116100 

Z 121200 
$ 124300 

. 127400 

132500 
0 135600 

1 140700 

2 144000 


Second 

Character 


A 000050 
B 000120 
C 000170 
D 000240 
E 000310 
F 000360 
G 000430 
H 000500 
I 000550 
J 000620 
K 000670 
L 000740 
M 001010 
N 001060 
O 001130 
P 001200 
Q 001250 
R 001320 
S 001370 
T 001440 
U 001510 

V 001560 
W 001630 
X 001700 

Y 001750 
Z 002020 
$ 002070 
. 002140 

002210 
0 002260 

1 002330 

2 002400 


Third 

Character 


A 000001 
B 000002 
C 000003 
D 000004 
E 000005 
F 000006 
G 000007 
H 000010 
I 000011 
J 000012 
K 000013 
L 000014 
M 000015 
N 000016 
O 000017 
P 000020 
Q 000021 
R 000022 
S 000023 
T 000024 
U 000025 

V 000026 
W 000027 
X 000030 

Y 000031 
Z 000032 
$ 000033 
. 000034 

000035 
0 000036 

1 000037 

2 000040 
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3 

147100 

3 

002450 

3 

000041 

4 

152200 

4 

002520 

4 

000042 

5 

155300 

5 

002570 

5 

000043 

6 

160400 

6 

002640 

6 

000044 

7 

163500 

7 

002710 

7 

000045 

8 

166600 

8 

002760 

8 

000046 

9 

171700 

9 

003030 

9 

000047 


C.3 MACRO SPECIAL CHARACTERS 
Character Function 


form feed 
line feed 
carriage return 
vertical tab 
: 


% 

tab 

space 

# 

@ 

( 

) 

, (comma) 

; 

+ 


* 

/ 

& 

1 

N 

' (apostrophe) 

< 

> 

t 

t 

\ 


Source line terminator, forces a new listing page 

Source line terminator 

Formatting character 

Source line terminator 

Label terminator 

Direct assignment indicator 

Register term indicator 

Item terminator, field terminator 

Item terminator, field terminator 

Immediate expression indicator 

Deferred addressing indicator 

Initial register indicator 

Terminal register indicator 

Operand field separator 

Comment field indicator 

Arithmetic addition operator or autoincrement 
indicator 

Arithmetic subtraction operator or autodecrement 
indicator 

Arithmetic multiplication operator 
Arithmetic division operator 
Logical AND operator 
Logical OR operator 
Double ASCII character indicator 
Single ASCII character indicator 
Assembly location counter 
Initial argument indicator 
Terminal argument indicator 
Universal unary operator 
Argument indicator 
MACRO numeric argument indicator 


C.4 ADDRESS MODE SYNTAX 

In the following syntax table, n represents am integer between 0 and 
7; R is a register expression; E represents any expression; ER 
represents either a register expression or an absolute expression in 
the range 0 to 7. 

On Register R Register R contains the operand. 

R is a register expression. 

In Deferred Register @R or (R) Register R contains the operand 

address. 
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2n Autoincrement (ER) + 


Deferred 

3n Autoincrement @(ER)+ 


4n Autodecrement -(ER) 


Deferred 

5n Autodecrement (ER) 


Index by the 
Register 

6n Specified E(ER) 


Deferred index 
by the Register 


7n Specified @E(ER) 

27 Immediate Operand #E 

37 Absolute address 8#E 

67 Relative address E 

77 Deferred relative 

address @E 


The contents of the register 
specified by ER are incremented 
after being used as the address 
of the operand. 


ER contains a pointer to the 
address of the operand. ER is 
incremented after use. 

The contents of register ER are 
decremented before being used as 
the address of the operand. 


The contents of register ER are 
decremented before being used as 
a pointer to the address of the 
operand. 


The value obtained when E is 
combined with the contents of 
the register specified (ER) is 
the address of the operand. 


E added to ER produces a pointer 
to the address of the operand. 

E is the operand. 

E is the operand address. 

E is the address of the operand. 


E is a pointer to the address of 
the operand. 


C.5 INSTRUCTIONS 

The tables of instructions which follow are grouped according to the 
operands they take and according to the bit patterns of their 
op-codes. 


The following symbols are used to indicate the instruction type 
format s 


OP Instruction mnemonic 

R Register Expression 

E Expression 

ER Register expression or expression 

0<«ER<=7 

AC Floating point register expression 

A General address specification 
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In the representation of op-codes, the following symbols are used: 


SS 

DD 

XX 


Source operand 


Specified by a 6-bit 
address mode 


Destination 

operand 

8-bit offset to a 
location 


Specified by a 6-bit 
address mode 

Branch instructions 


R 


Integer between 0 
and 7 


Represents a general 
register 


Symbols used in the description of instruction operations are: 

SE Source Effective Address 

FSE Floating Source Effective Address 

DE Destination Effective Address 

FDE Floating Destination Effective Address 

I I Absolute Value of 

( ) Contents of 

-*■ Becomes 


The condition codes in the processor status word (PS) are affected by 
the instructions; these condition codes are represented as follows: 


N 

Z 

V 

C 


Negative bit: 
Zero bit: 
Overflow bit: 

Carry bit: 


Set if the result is negative 
Set if the result is zero 
Set if the operation caused an 
overflow 

Set if the operation caused a 
carry 


In the representation of the instruction's effect on the condition 
codes, the following symbols are used: 


* Conditionally set 

- Not affected 

0 Cleared 

1 Set 

To set conditionally means to use the instruction's result to 
determine the state of the code. 


Logical operators are represented by the following symbols: 
1 Inclusive OR 

(J) Exclusive OR 

& AND 


Used over a symbol to represent 
the l's complement of the symbol 
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C.5.1 Double Operand Instructions (OP A,A) 


Op—Code 

01SSDD 

11SSDD 

Mnemonic 

Stands for 

Operation 

Status Word 

Condition 

Codes 

N Z V C 

MOV 

MOVB 

MOVe 

MOVe Byte 

(SE) -*• (DE) 

* * 

0 - 

02SSDD 

12SSDD 

CMP 

CMPB 

CoMPare 

CoMPare Byte 

(SE)-(DE) 

* * 

* * 

03SSDD 

13SSDD 

BIT 

BITB 

Bit Test 

Bit Test Byte 

(SE) & (DE) 

* * 

0 - 

04SSDD 

14SSDD 

BIC 

BICB 

Bit Clear 

Bit Clear Byte 

(SE) & (DE) (DE) 

* * 

0 - 

05SSDD 

15SSDD 

BIS 

BISB 

Bit Set 

Bit Set Byte 

(SE) I (DE) - (DE) 

* * 

0 - 

06SSDD 

16SSDD 

ADD 

SUB 

ADD 

SUBtract 

(SE) + (DE) (DE) 
(DE) - (SE) (DE) 

* * 

* * 

* * 

* * 

C.5.2 

Single Operand 

Instructions 

(OP A) 



Op-code 

Mnemonic 

Stands for 

Operation 

Status Word 

Condition 

Codes 

N Z V C 

0050DD 

1050DD 

CLR 

CLRB 

CLeaR 

CLeaR Byte 

0 -*■ (DE) 

0 1 

0 0 

0051DD 

1051DD 

COM 

COMB 

COMplement 
COMplement Byte 

( 51 ) -*■ (DE) 

* * 

0 1 

0052DD 

1052DD 

INC 

INCB 

INCrement 
INCrement Byte 

(DE) + 1 -*■ (DE) 

* * 

* 1 

0053DD 

1053DD 

DEC 

DECB 

DECrement 
DECrement Byte 

(DE) - 1 -»• (DE) 

* * 

* - 

0054DD 

1054DD 

NEG 

NEGB 

NEGate 

NEGate Byte 

(DE) + 1 -*• (DE) 

* * 

* * 

0055DD 

1055DD 

ADC 

ADCB 

ADd Carry 

ADd Carry Byte 

(DE) + (C) (DE) 

* * 

* * 

0056DD 

1056DD 

SBC 

SBCB 

SuBtract Carry 
SuBtract Carry 
Byte 

(DE) - (C) + (DE) 

* * 

* * 

0057DD 

1057DD 

TST 

TSTB 

TeST 

TeST Byte 

(DE) 

* * 

0 0 
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C.5.3 Rotate/Shift 


Op-Code 

Mnemonic 

Stands for 

Operation 



Status Word 

Condition 

Codes 

N Z V C 

0060DD 

ROR 

Rotate Right EpH i . 

, , i 

-J 

* 

* 

* 

* 

106ODD 

RORB 

Rotate Right 

L.'J Ip- 1 - 

. . i 


* 

* 

* 

* 



Byte 

T —— 1 L_ 

-ny 

r 





0061DD 

ROL 

Rotate Left 

m-c:,.: , , 

.. i 

—J 

* 

* 

* 

* 

1061DD 

ROLB 

Rotate Left 

Li ■ ■ ” , , i 1 L^_i_ 

i 


* 

* 

* 

* 



Byte 

^^ t 

-m- 






0062DD 

ASR 

Arithmetic 




* 

* 

* 

* 



Shift Right 

d, 1 ~ 1 ■, i; ■ i ■ ■ 

i . 






1062DD 

ASRB 

Arithmetic 




* 

* 

* 

* 



Shift Right 

cL 1 i.u,'— 

ZTZZZZHD 







Byte 








0063DD 

ASL 

Arithmetic 

eh; 

-.1 i 

^y° 

* 

* 

* 

* 



Shift Left 








1063DD 

AS LB 

Arithmetic 

EH7 . I.HZ3H 

-H—— 1 —■— 

* 

* 

* 

* 



Shift Left 










Byte 








0001DD 

JMP 

JUMP 

DE -*(PC) 



- 

- 

- 

- 

0003DD 

SWAB 

SWAp Bytes 

1 1 1 J *T 1 ‘ 

1 ■ 


* 

* 

0 

0 

The following instructions are 

available on the 

PDP-11/03 

(LSI/11) 

only: 
















Status Word 







Condition 

Op-Code 

Mnemonic 

Stands for 

Operation 



uoaes 

N Z 

V 

c 

1067DD 

MFPS 

Move byte From (DE)«-PSW 



* 

* 

0 

_ 


Processor Status 
word 


1064SS MTPS Move byte To (SE)^-PSW * * * * 

Processor Status 
word 

The following instructions are available on the PDP-11/35,40,45 as 
noted: 

status Word 

Condition 

Codes 

Op-Code Mnemonic Stands for Operation N Z V C 


11/35, 11/40, 11/45 with KT11 


0065SS MFPI Move From 

Previous 

Instruction 

space 


(SE) (TEMP) 
(SP) —2 -► (SP) 
(TEMP) -*■ ( (SP) ) 


* * 0 - 
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11/45 with KTll only 


1065SS 

MFPD 

Move From 

(SE) -► (TEMP) 

* 

* 

0 

— 



Previous 

(SP)-2 ->■ (SP) 







Data space 

(TEMP) -► ( (SP) ) 





11/35, 

11/40, 11/45 with KTll 






0066DD 

MTPI 

Move To 

( (SP)) -*■ (TEMP) 

* 

* 

0 

- 



Previous 

(SP+2) -►(SP) 







Instruction 

space 

(TEMP) ■+ (DE) 





11/45 with KTll only 







1066DD 

MTPD 

Move To 

( (SP)) -► (TEMP) 

* 

* 

0 

- 



Previous 

(SP+2) (SP) 







Data space 

(TEMP) ->■ (DE) 





1701DD 

LDFPS 

Load FPP 
program status 

DE -*• FPS 

- 

— 

mm 

* 

11/35, 

11/40, 11/45 







0067DD 

SXT 

Sign eXTend 

0 -*■ DE if N bit 
is clear 
—1 DE if N bit 
is set 


* 



11/45 with FP11-B 







0707DD 

NEGD 

NEGate Double 

- (FDE) -»• FDE 





0707DD 

NEGF 

NEGate Floating 

- (FDE) -*• FDE 

* 

* 

0 

0 

1702DD 

STFPS 

STore Floating > 
Point processor 

I See Chapter 7 

- 

- 

- 

- 



program Status ! 

[ in PDP-11/45 
r Processor 





1703DD 

STST 

STore floating 
point processor J 
STatus 

1 Handbook 





1704DD 

CLRD 

CLeaR Double 

0 (FDE) 

0 

1 

0 

0 

1704DD 

CLRF 

CLeaR Floating 

0 -► (FDE) 

0 

1 

0 

0 

1705DD 

TSTD 

TeST Double 

(FDE) 

* 

* 

0 

0 

1705DD 

TSTF 

TeST Floating 

(FDE) 

* 

* 

0 

0 

1706DD 

ABSD 

make ABSolute 
Double 

|(FDE)| (FDE) 

0 

* 

0 

0 

1706DD 

ABSF 

make ABSolute 

| (FDE)| -*■ (FDE) 

0 

* 

0 

0 


Floating 


January 1976 
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C.5.4 Operate Instructions (OP) 






Status 

i Word 





Condition 





Codes 



Op-Code 

Mnemonic 

Stands for 

Operation 

N 

z 

V 

c 

000000 

HALT 

HALT 

The computer stops 
all functions. 

- 

- 

- 

- 

000001 

WAIT 

WAIT 

The computer stops 
and waits for an 
interrupt. 

— 

— 

— 

— 

000002 

RTI 

ReTurn from 

The PC and ST are 

* 

* 

* 

* 



Interrupt 

popped off the SP 







(Return from 

stack: 







Trap) 

( (SP)) + (PC) 

(SP) +2 -► (SP) 

((SP)) +(ST) 

(SP) +2 -*• (SP) 





000005 

RESET 

RESET 

Returns all I/O 
devices to 

- 

- 

- 

- 




power-on state. 





000241 

CLC 

CLear Carry bit 

0 -»C 

- 

- 

- 

0 

000261 

SEC 

SEt Carry bit 

UC 

- 

- 

- 

1 

000242 

CLV 

CLear overflow 

0 +V 

- 

- 

0 

- 

000262 

SEV 

SEt overflow 
bit 

1 -*• V 

- 

- 

1 

- 

000244 

CLZ 

CLear Zero bit 

0 -*■ z 

- 

0 

- 

- 

000264 

SEZ 

SEt Zero bit 

1 z 

- 

1 

- 

- 

000250 

CLN 

CLear Negative 
bit 

0+N 

0 

- 

- 

- 

000270 

SEN 

SEt Negative 
bit 

1 -*• N 

1 

- 

- 

- 

000257 

CCC 

Clear all 

0 + N 

0 

0 

0 

0 



Condition 

0 z 







Codes 

0 + V 

0 + c 





000277 

see 

Set all 

1 N 

1 

1 

1 

1 



Condition 

1 Z 







Codes 

1 V 

1 -»-c 





000240 

NOP 

No Operation 
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The following instructions are available on the PDP—11/45 with FP11—B 
only: 


Op-Code 

Mnemonic 

Stands for 

Operation 

170000 

CFCC 

Copy Floating 
Condition Code 

Copy FPP 
condition codes 
into CPU condi¬ 
tion codes. 

170011 

SETD 

SET Double 

floating 

mode 

FPP set to 

double 

precision 

170001 

SETF 

SET Floating 
mode 

FPP set to 
single 
precision 
mode 

170002 

SETI 

SET Integer 
mode 

FPP set for 
integer data 
(16 bits) 

170012 

SETL 

SET Long 
integer mode 

FPP set for 
long integer 
data (32 bits) 

All 11/45 

*s, with and 

without FP11-B 


000006 

RTT 

ReTurn from 
inTerrupt 

Same as RTI 
instruction but 
inhibits trace 
trap 

C.5.5 Trap Instructions (OP or OP e 

*(OP (only)) 

where 0<=E<“377(8) 

Op-Code 

Mnemonic 

Stands for 

Operation 

*000003 

BPT 

Breakpoint 

Trap 

Trap to 
location 14. 

This is used 
to call ODT. 

*000004 

IOT 

Input Output 
Trap 

Trap to 
location 20. 

This is used 


to call IOX. 


Status Word 

Condition 

Codes 

N Z V C 

* * * * 


* * * * 


Status Word 

Condition 

Codes 

N Z V C 

* * * * 


* * * * 
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104000- EMT EMulator 

104377 Trap 


104400- TRAP TRAP 

104777 


Trap to 
location 30, 

This is used 
to call system 

programs, 

Trap to 
location 34. 

This is used 
to call any 
routine desired 
by the programmer. 


C.5.6 


Branch Instructions OP E 

(where —128(decimal)< (E— 


-2)/2<127(decimal)) 


Condition to be 
met if branch is 


Op-Code 

Mnemonic 

Stands for 

to occur 

0004XX 

BR 

BRanch always 


0010XX 

BNE 

Branch if Not Equal (to zero) 

z=o 

0014XX 

BEQ 

Branch if EQual (to zero) 

Z=1 

0020XX 

BGE 

Branch if Greater than or 

Equal (to zero) 

N® V-0 

0024XX 

BLT 

Branch if Less Than (zero) 

n(T) V = 1 

0030XX 

BGT 

Branch if Greater Than 
(zero) 

Z l (N (T) V) =0 

0034XX 

BLE 

Branch if Less than or 

Equal (to zero) 

ZI (N (D V) -1 

1000XX 

BPL 

Branch if PLus 

N=0 

1004XX 

BMI 

Branch if Minus 

N-l 

1010XX 

BHI 

Branch if Higher 

c(D Z-0 

1014XX 

BLOS 

Branch if LOwer or Same 

ClZ-1 

1020XX 

BVC 

Branch if overflow Clear 

v=o 

1024XX 

BVS 

Branch if overflow Set 

V=1 

1030XX 

BCC (or 
BHIS) 

Branch if Carry Clear 
(or Branch if High or Same) 

c=o 

1034XX 

BCS (or 
BLO) 

Branch if Carry Set (or 

Branch if LOw) 

C=1 
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1 


C.5.7 Register Destination (OP ER,A) 


Op-Code Mnemonic Stands for 

004RDD JSR Jump to 

SubRoutine 


Status Word 

Condition 

Codes 

Operation N Z V C 


Push register 
on the SP stack, 
put the PC in 
the register: 

DE TEMP (TEMP= 
temporary storage 
register internal 
to processor.) 


(SP) -2 SP 
(REG) > (SP) 

(PC) + REG 
(TEMP) -+ PC 

TwJ? ll0Wing instruction is available only on the 11 / 35 , 
074RDD XOR exclusive OR (R) 0 (de) -»• (DE) * * 


11/40, 
0 - 




C.5.8 Register-Offset (OP R,E) 

^he^following instruction is available only on the PDP-ll/ 35 , 11/40, 


Op-Code Mnemonic 


Stands for 


Operation 


N Z V C 


077RDD SOB 


Subtract One 
and Branch 


(R) -1-*- (R) 
(PC)—(2*DE) 


(PC) 


C.5.9 Subroutine Return (OP ER) 


Op-Code 

Mnemonic 

Stands 

for 

00020 R 

RTS 

ReTurn from 
Subroutine 


Operation 

Put register 
in PC and pop 
old contents from 
SP stack into 
register. 


N Z V C 
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C.5.10 Source-Register (OP A,R) 

only-° 110Wing instructions are available on the 11/35, 11/40, 11/45 


Op-Code 

Mnemonic 

Stands for 

071RSS 

DIV 

Divide 

070RSS 

MUL 

MULtiply 

072RSS 

ASH 

Arithmetic 



SHift 


073RSS ASHC Arithmetic 

SHift 

Combined 


Status Word 
Floating 
Condition 
Codes 

Operation N Z V C 


(R) , (Rll)/(SRC) - (R) , (RU) 

* * * * 

(R)*(SRC) + (R),(Rll) 

* * * * 

R is shifted 
according to 
low-order 6-bits 
of source 


d,'.. i . . u-^hEl 


or 

—. ■ i . . i r ■ i . . i . . ^ H — • 

R,RVL are shifted * * * * 

according to low- 
order 6 bits of 
source 



or 



C.5.11 Floating-Point Source Double Register (OP A,AC) 


The following instructions are available on the PDP-11/45 with 
only: 


FP11-B 


Status Word 
Floating 
Condition 
Codes 

Op-Code Mnemonic Stands for Operation fn FZ FV FC 

172 (AC) SS ADDD ADD Double (FSE) +(AC) -*■ (AC) * * * g 
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172(AC)SS ADDF 

173(AC+4)SS 

CMPD 


173(AC+4)SS 

CMPF 


174(AC+4)SS 

DIVD 


174(AC+4)SS 

DIVF 


177(AC+4)SS 

LDCDF 


177(AC+4)SS 

LDCFD 


172(AC+4)SS 

LDD 

172(AC+4)SS 

LDF 

171(AC+4)SS 

MODD 


171(AC+4)SS 

MODF 


171(AC)SS MULD 


171(AC)SS MULF 


173(AC)SS SUBD 


173(AC)SS SUBF 


Instruction, and Character Code Summaries 

ADD Floating (FSE) +(AC)-► (AC) * * * 0 

(FSE) - (AC) * * 0 0 


CoMPare 

Double 


CoMPare 

Floating 


Divide 

Double 


Divide 

Floating 


(FSE) -(AC) 

(AC)/(FSE)(AC) 

(AC) / (FSE) -*■ (AC) 


LoaD and Con- (FSE) (AC) 
vert from 
Double to 
Floating 

LoaD and Con- (FSE) (AC) 
vert from 
Floating to 
Double 


* * * 0 


* * * o 


* * * o 


LoaD Double 

(FSE) -*■ (AC) 

* 

* 

0 

0 

LoaD Floating 

(FSE) -*■ (AC) 

* 

* 

0 

0 

Multiply and 
integenze 

(AC) * (FSE) (AC) , 

(AC1) 




double 

* 

* 

* 

* 

Multiply and 
integer!ze 
floating¬ 
point 

(AC)* (FSE) -v (AC) 

* 

* 

* 

0 

MULtiply 

Double 

(AC) * (FSE) (AC) 

* 

* 

* 

0 

MULtiply 

Floating 

(AC) * (FSE) (AC) 

* 

* 

* 

0 

SUBtract 

Double 

(FSE) -(AC)-*- (AC) 

* 

* 

* 

0 

SUBtract 

Floating 

(FSE) — (AC) -*■ (AC) 

* 

* 

* 

0 
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C.5.12 Source-Double Register (OP A,AC) 

The following instructions are available on the PDP-11/45 with FP11-B 
only: 


Op-Code 

Mnemonic 

Stands for Operation 

Status Word 
Condition Codes 
FN FZ FV FC 

177(AC)SS 

LDCID 

LoaD and Con- (SE) -*■ (AC) 
vert Integer 
to Double 

* 

* 

* 

0 

177(AC)SS 

LDCIF 

LoaD and Con- (SE) -► (AC) 
vert Integer 
to Floating 

* 

* 

* 

0 

177(AC)SS 

LDCLD 

LoaD and Con- (SE) -+ (AC) 
vert Long 
integer to 

Double 

* 

* 

* 

0 

177(AC)SS 

LDCLF 

LoaD and Con- (SE) (AC) 
vert Long In¬ 
teger to 

Floating 

* 

* 

* 

0 

176(AC+4)SS 

LDEXP 

LoaD EXPonent (SE)+200 (AC EXP) 

* 

* 

0 

0 


C.5.13 Double Register-Destination (OP AC,A) 

The following instructions are available on the PDP-11/45 with FP11-B 
only: 


Op-Code 

Mnemonic 

Stands for 

Operation 

176(AC)DD 

STCFD 

STore, Con¬ 
vert from 
Floating to 
Double 

(AC) -*• 

(FDE) 

176(AC)DD 

STCDF 

STore, Con¬ 
vert from 
Double to 
Floating 

(AC) + 

(FDE) 

175(AC+4)DD 

STCDI(l) 

STore, Con¬ 
vert from 
Double to 
Integer 

(AC) •+■ 

(FDE) 


Status Word 
Condition Codes 
FN FZ FV FC 

* * * 0 


* * * 0 


* * 0 * 


(1)These instructions set both the floating-point and processor 
condition codes as indicated. 
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175(AC+4)DD 

STCDL(l) STore, Con- (AC) (FDE) 
vert from 
Double to 
Long integer 


175(AC+4)DD 

STCFI(l) STore, Con- (AC) •+ (FDE) 
vert from 
Floating to 
Integer 


* * 0 * 


* * o * 


174(AC+4)DD 

STCFL(l) 

STore, Con¬ 
vert from 
Floating to 
Long integer 

(AC) -*■ (FDE) 

174(AC)DD STD 

STore Double 

(AC) -*■ (FDE) 


* * o * 


174(AC)DD STF STore 

Floating 

175(AC)DD STEXP(l) STore 

EXPonent 


(AC) -+ (FDE) 


(AC EXP)-200 -► (DE) **00 


C.5.14 Number 


The following instruction is available on the 11/35, 11/40, 11/45 

only: 


Op-Code 


Mnemonic Stands for 


Operation 


Status Word 
Condition Codes 
N Z V C 


0064NN MARK MARK 


Stack cleanup on 
return from sub¬ 
routine. 


C.5.15 Priority 

The following instruction is available on the PDP—11/45 only: 

Status Word 
Condition 
Codes 

Operations N Z V C 


(X) (PS) 
(bits 7-5) 


Op-Code Mnemonic Stands for 

00023N SPL Set Priority 

Level 


the floating-point and processor 


(1)These instructions set both 
condition codes as indicated. 
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C.6 ASSEMBLER 
Form 


\ 

tBn 

tCn 

tDn 

tFn 

tOn 

.ASCII string 

.ASCIZ string 

.ASECT 
.BLKB exp 

.BLKW exp 


DIRECTIVES 
Described in 

Manual Section Operation 


5.5.3.3 


5.5.3.3 


5.6.3.3 


5.5.4.2 

5.5.6.2 

5.5.4.2 

5.5.6.2 

5.5.4.2 


5.5.3.4 


5.5.3.5 


5.5.9 
5.5.5.3 

5.5.5.3 


A single quote character (apostrophe) 
followed by one ASCII character 
generates a word containing the 7-bit 
ASCII representation of the character 
in the low-order byte and zero in the 
high-order byte. 

A double quote character followed by 
two ASCII characters generates a word 
containing the 7-bit ASCII 
representation of the two characters. 

A backslash preceding an argument 
causes the number to be treated in the 
current radix. 

Temporary radix control; causes the 
number n to be treated as a binary 
number. 

Creates a word containing the one's 
complement of n. 

Temporary radix control; causes the 
number n to be treated as a decimal 
number. 

Creates a one-word floating point 
quantity to represent n. 

Temporary radix control; causes the 
number n to be treated as an octal 
number. 

Generates a block of data containing 
the ASCII equivalent of the character 
string (enclosed in delimiting 
characters) one character per byte. 

Generates a block of data containing 
the ASCII equivalent of the character 
string (enclosed in delimiting 
characters) one character per byte 
with a zero byte following the 
specified string. 

Begin or resume absolute section. 

Reserves a block of storage space exp 
bytes long. 

Reserves a block of storage space exp 
words long. 
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.BYTE expl. 

5.5.3.1 

eXp2 fee* 

.CSECT symbol 

5.5.9 

.DSABL arg 

CM 

• 

in 

• 

in 

.ENABL arg 

5.5.2 

.END 

5.5.7.1 

.END exp 

.ENDC 

5.5.11 

. ENDM 

5.6.1.2 

.ENDM symbol 


.EOT 5.5.7.2 

.ERROR exp,string 5.6.5 


.EVEN 


5.5.5.1 


.FLT2 argl, 5.5.6.1 

arg2,.. . 


.FLT4 argl, 5.5.6.1 

arg2,... 


.GLOBL syml, 5.5.10 

sym2,... 

.IDENT symbol 5.5.1.5 


.IF cond, 
arguments 


5.5.11 


Generates successive bytes of data 
containing the octal equivalent of the 
expression(s) specified. 

Begins or resumes named or unnamed 
relocatable section. 

Disables the assembler function 
specified by the argument. 

Provides the assembler function 
specified by the argument. 

Indicates the physical end of the 
source program. An optional argument 
specifies the transfer address. 

Indicates the end of a condition 
block. 

Indicates the end of the current 
repeat block, indefinite repeat block, 
or macro. The optional symbol, if 
used, must be identical to the macro 
name. 

Ignored. Indicates End-of-Tape which 
is detected automatically by the 
hardware. 

Causes a text string to be output to 
the listing containing the optional 
expression specified and the indicated 
text string. The line will be flagged 
with the "P" error code. 

Ensures that the assembly location 
counter contains an even address by 
adding 1 if it is odd. 

Generates successive two-word float¬ 
ing point equivalents for the 
floating-point numbers specified as 
arguments. 

Generates successive four-word float¬ 
ing point equivalents for the 
floating-point numbers specified as 
arguments. 

Defines the symbol(s) specified as 
global symbol(s). 

Provides a means of labeling the 
object module produced as a result of 
assembly. This directive is not 
supported by RT-11, but is included 
for compatibility with other systems. 

Begins a conditional block of source 
code which is included in the assembly 
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• Ip F 5.5.11.1 


•IFT 5.5.11.1 


.IFTF 5.5.11.1 


•IIF cond,arg, 5.5.11.2 
statement 


.IRP sym, 5.6.6 

<argl,arg2,...> 


•IRPC sym,string 5.6.6 


•LIMIT 5.5.8 

•LIST 5.5.1.1 

.LIST arg 


.MACRO sym,argl, 5.6.1.1 
argl,... 

.MCALL 5.6.8 

.MEXIT 5.6.1.3 


only if the stated condition is met 
with respect to the argument(s) 
specified. 

Appears only within a conditional 
block and indicates the beginning of a 
section of code to be assembled if the 
condition tested false. 

Appears only within a conditional 
block and indicates the beginning of a 
section of code to be assembled if the 
condition tested true. 

Appears only within a conditional 
block and indicates the beginning of a 
section of code to be unconditionally 
assembled. 

Acts as a one-line conditional block 
where the condition is tested for the 
argument specified. The statement is 
assembled only if the condition tests 
true. 

Indicates the beginning of an indef¬ 
inite repeat block in which the 
symbol specified is replaced with 
successive elements of the real 
argument list (which is enclosed in 
angle brackets). 

Indicates the beginning of an 
indefinite repeat block in which the 
symbol specified takes on the value of 
successive characters in the character 
string. 

Reserves two words into which the 
Linker inserts the low and high 
addresses of the relocated code. 

Without an argument, .LIST increments 
the listing level count by 1. with an 
argument, .LIST does not alter the 
Listing level count but formats the 
assembly listing according to the 
argument specified. 

Indicates the start of a macro with 
the specified name containing the 
dummy arguments specified. 

Used to specify the names of all 
system macro definitions not defined 
in the current program but required by 
the program. 

Causes an exit from the current macro 
or indefinite repeat block. 
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.NARG symbol 5.6.4 


,NCHR sym,<string> 5.6.4 


.NLIST 
.NLIST arg 


5.5.1.1 


.NTYPE symbol,arg 5.6.4 


.ODD 


5.5.5.2 


.PAGE 


5.5.1.6 


.PRINT exp,string 5.6.5 


.RADIX n 


5.5.4.1 


,RAD50 string 5.5.3.6 


,REPT exp 5.6.7 


,SBTTL string 5.5.1.4 


.TITLE string 5.5.1.3 


Appears only within a macro definition 
and equates the specified symbol to 
the number of arguments in the macro 
call currently being expanded. 

Can appear anywhere in a source 
program; equates the symbol specified 
to the number of characters in the 
string (enclosed in delimiting 
characters)• 

Without an argument, .NLIST decrements 
the listing level count by 1. With an 
argument, .NLIST deletes the portion 
of the listing indicated by the 
argument. 

Appears only in a macro definition and 
equates the low-order six bits of the 
symbol specified to the six—bit 
addressing mode of the argument. 

Ensures that the assembly location 
counter contains an odd address by 
adding 1 if it is even. 

Causes the assembly listing to skip to 
the top of the next page. 

Causes a text string to be output to 
the listing containing the optional 
expression specified and the indicated 
text string. 

Alters the current program radix to n, 
where n can be 2, 4, 8, or 10. 

Generates a block of data containing 
the Radix-50 equivalent of the 
character string (enclosed in 
delimiting characters). 

Begins a repeat block. Causes the 
section of code up to the next .ENDM 
or .ENDR to be repeated exp times. 

Causes the string to be printed as 
part of the assembly listing page 
header. The string part of each 
.SBTTL directive is collected into a 
table of contents at the beginning of 
the assembly listing. 

Assigns the first symbolic name in the 
string to the object module and causes 
the string to appear on each page of 
the assembly listing. One .TITLE 
directive should be issued per 
program. 
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.WORD expl, 5.5.3.2 

exp2,... 


C.7 MACRO/CREF SWITCHES 


Generates successive words of data 
containing the octal equivalent of the 
expression(s) specified. 


C.7.1 Listing Control Switches 
Switch Meaning 

/Lsarg These switches are used to control listing output. 
/Nsarg Arguments which are valid for either switch include: 


Arg Controls Listing of: 


SEQ 

LOC 

BIN 

BEX 

SRC 

COM 

MD 

MC 

ME 

MEB 

CND 

LD 

TOC 

TTM 

SYM 

<no arg> 


Source line sequence numbers 
Location counter 
Generated binary code 
Binary extensions 
Source code 
Comments 

Macro definitions and repeat range definitions 

Macro calls and repeat range expansions 

Macro expansions 

Macro expansion binary code 

Unsatisfied conditions and all .IF 

and .ENDC statements. 

Listing directives having no arguments 
Table of contents 
Listing output format 
Symbol table 

/N with no argument causes only table of contents, 
symbol table, and error listings to be produced. 


/L with no argument causes .LIST and .NLIST 
directives without arguments which appear in the 
source program to be ignored. 

C.7.2 Function Control Switches 


Switch Meaning 

/D:arg These switches are used to enable or disable certain 
/E:arg functions in source input files. Valid arguments 

include: 


Arg Enables or Disables: 


ABS 

AMA 

CDR 

FPT 

LC 

LSB 

PNC 


Absolute binary output 

Assembly of all absolute addresses as relative 
addresses 

Source columns 73 and greater to be treated as 
comments 

Floating point truncation 
Accepts lower case ASCII input 
Local symbol block 
Binary output 
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C.7.3 CREF Switches 


Switch 

Produces Cross-Reference of: 

/C:S 

/CsR 

/CsM 

/C:P 

/CsC 

/CsE 

User-defined symbols 
Register symbols 

MACRO symbolic names 
Permanent symbols 
Control sections 

Error codes 


/C:<no arg> Equivalent to /CsSsMsE 
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C.8 OCTAL-DECIMAL CONVERSIONS 


0000 

to 

0777 

(Octal) 


Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 


0000 

to 

0511 

(Decimal) 


Decimal 

4096 

8192 

12288 

16384 

20480 

24576 

28672 


0000 

0010 

0020 

0030 

00«0 

0050 

0060 

0070 

0100 

0110 

0120 

0130 

0140 

0150 

0160 

0170 

0200 

0210 

0220 

0230 

0240 

0250 

0260 

0270 

0300 

0310 

0320 

0330 

0340 

0350 

0360 

0370 


1 


2 


0000 0001 
0008 0009 
0016 0017 
0024 0025 
0032 0033 
0040 0041 
0048 0049 
0056 0057 


0002 

0010 

0018 

0026 

0034 

0042 

0050 

0058 


0003 0004 
0011 0012 
0019 0020 
0027 0028 
0035 0036 
0043 0044 
0051 0052 
0059 0060 


0005 0006 
0013 0014 
0021 0022 
0029 0030 
0037 0038 
0045 0046 
0053 0054 
0061 0062 


0007 

0015 

0023 

0031 

0039 

0047 

0055 

0063 


0064 

0072 

0080 

0088 

0096 

0104 

0112 

0120 

0128 
0136 
0144 
0152 
0160 
Cl 68 
0176 
0184 

0192 

0200 

0208 

0216 

0224 

0232 

0240 

0248 


0065 

0073 

0081 

0089 

0097 

0105 

0113 

0121 

0129 

0137 

0145 

0153 

0161 

0169 

0177 

0185 


0066 0067 
0074 0075 
0082 0083 
0090 0091 
0098 0099 
0106 0107 
0114 0115 
0122 0123 

0130 0131 
0138 0139 
0146 0147 
0154 0155 
0162 0163 
0170 0171 
0178 0179 
0186 0187 


0193 0194 
0201 0202 
0209 0210 
0217 0218 
0225 0226 
0233 0234 
0241 0242 
0249 0250 


0195 

0203 

0211 

0219 

0227 

0235 

0243 

0251 


0068 

0076 

0084 

0092 

0100 

0108 

0116 

0124 

0132 

0140 

0148 

0156 

0164 

0172 

0180 

0188 

0196 

0204 

0212 

0220 

0228 

0236 

0244 

0252 


0069 

0077 

0085 

0093 

0101 

0109 

0117 

0125 


0070 0071 
0078 0079 
0086 0087 
0094 0095 
0102 0103 

0110 01lI 
0118 0119 
0126 0127 


0133 0134 
0141 0142 
0149 0150 
0157 0158 
0165 0166 
0173 0174 
0181 0182 
0189 0190 


0135 

0143 

0151 

0159 

0167 

0175 

0183 

0191 


0197 

0205 

0213 

0221 

0229 

0237 

0245 

0253 


0206 0207 
0214 0215 
0222 0223 
0230 0231 
0238 0239 
0246 0247 
0254 0255 


1000 

to 

1777 

(Octal) 


0512 

to 

1023 

(Decimal) 


1000 

1010 

1020 

1030 

1040 

1050 

1060 

1070 

1100 

1110 

1120 

1130 

1140 

1150 

1160 

1170 

1200 

1210 

1220 

1230 

1240 

1250 

1260 

1270 

1300 

1310 

1320 

1330 

1340 

1350 

1360 

1370 


1 


0512 

0520 

0528 

0536 

0544 

0552 

0560 

0568 

0576 

0584 

0592 

0600 

0608 

0616 

0624 

0632 


0513 0514 
0521 0522 
0529 0530 
0537 0538 
0545 0546 
0553 0554 
0561 0562 
0569 0570 

0577 0578 
0585 0586 
0593 0594 
0601 0602 
0609 0610 
0617 0616 
0625 0626 
0633 0634 


0515 

0523 

0531 

0539 

0547 

0555 

0563 

0571 

0579 

0587 

0595 

0603 

0611 

0619 

0627 

0635 


0516 

0524 

0532 

0540 

0548 

0556 

0564 

0572 


0517 

0525 

0533 

0541 

0549 

0557 

0565 

0573 


0580 0581 
0588 0589 
0596 0597 
0604 0605 
0612 0613 
0620 0621 
0628 0629 
0636 0637 


0518 0519 
0526 0527 
0534 0535 
0542 0543 
0550 0551 
0558 0559 
0566 0567 
0574 0575 

0582 0583 
0590 0591 
0598 0599 
0606 0607 
0614 0615 
0622 0623 
0630 0631 
0638 0639 


0640 0641 
0648 0649 
0656 0657 
0664 0665 
0672 0673 
0680 0681 
0688 0689 
0696 0697 


0642 0643 
0650 0651 
0658 0659 
0666 0667 
0674 0675 
0682 0683 
0690 0691 
0698 0699 


0704 

0712 

0720 

0728 

0736 

0744 

0752 

0760 


0705 

0713 

0721 

0729 

0737 

0745 

0753 

0761 


0706 

0714 

0722 

0730 

0738 

0746 

0754 

0762 


0707 

0715 

0723 

0731 

0739 

0747 

0755 

0763 


0644 

0652 

0660 

0668 

0676 

0684 

0692 

0700 

0708 

0716 

0724 

0732 

0740 

0748 

0756 

0764 


0645 0646 
0653 0654 
0661 0662 
0669 0670 
0677 0678 
0685 0686 
0693 0694 
0701 0702 


0647 

0655 

0663 

0671 

0679 

0687 

0695 

0703 


0709 

0717 

0725 

0733 

0741 

0749 

0757 

0765 


0710 0711 
0718 0719 
0726 0727 
0734 0735 
0742 0743 
0750 0751 
0758 0759 
0766 0767 


0400 

0410 

0420 

0430 

0440 

0450 

0460 

0470 

0500 

0510 

0520 

0530 

0540 

0550 

0560 

0570 

0600 

0610 

0620 

0630 

0640 

0650 

0660 

0670 


0256 0257 
0264 0265 
0272 0273 
0280 0281 
0288 0289 
0296 0297 
0304 0305 
0312 0313 


0320 

0328 

0336 

0344 

0352 

0360 

0368 

0376 


0321 

0329 

0337 

0345 

Q353 

0361 

0369 

0377 


0258 

0266 

0274 

0282 

0290 

0298 

0306 

0314 

0322 

0330 

0338 

0346 

0354 

0362 

0370 

0378 


0259 

0267 

0275 

0283 

0291 

0299 

0307 

0315 

0323 

0331 

0339 

0347 

0355 

0363 

0371 

0379 


0260 

0268 

0276 

0284 

0292 

0300 

0308 

0316 

0324 

0332 

0340 

0348 

0356 

0364 

0372 

0380 


0261 

0269 

0277 

0285 

0293 

0301 

0309 

0317 


0262 0263 
0270 0271 
0278 0279 
0286 0287 
0294 0295 
0302 0303 
0310 0311 
0318 0319 


0325 0326 
0333 0334 
0341 0342 
0349 0350 
0357 0358 
0365 0366 
0373 0374 
0381 0382 


0327 

0335 

0343 

0351 

0359 

0367 

0375 

0383 


0384 0385 
0392 0393 
0400 0401 
0408 0409 
0416 0417 
0424 0425 
0432 0433 
0440 0441 


0386 0387 
0394 0395 
0402 0403 
0410 0411 
0418 0419 
0426 0427 
0434 0435 
0442 0443 


0388 0389 
0396 0397 
0404 0405 
0412 0413 
0420 0421 
0428 0429 
0436 0437 
0444 0445 


0390 0391 
0398 0399 
0406 0407 
0414 0415 
0422 0423 
0430 0431 
04 38 04 39 
0446 0447 


0700 

0448 

0449 

0450 

0451 

0452 

0453 

i 0454 

0455 

0710 

0456 

0457 

0458 

0459 

0460 

0461 

0462 

0463 

0720 

0464 

0465 

0466 

0467 

0468 

0469 

0470 

0471 

0730 

0472 

0473 

0474 

0475 

0476 

0477 

0478 

0479 

0740 

0480 

0481 

0482 

0483 

0484 

0485 

0486 

0487 

0750 

0488 

0489 

0490 

0491 

0492 

0493 

0494 

0495 

0760 

0496 

0497 

0498 

0499 

0500 

0501 

0502 

0503 

0770 

0504 

0505 

0506 

0507 

0508 

0509 

0510 

0511 


0 

1 

2 

3 

4 

5 

6 

7 

1400 

0768 

0769 

077Q 

0771 

0772 

0773 

0774 

0775 

1410 

0776 

0777 

0778 

0779 

0780 

0781 

0782 

0783 

1420 

0784 

0785 

0786 

0787 

0788 

0789 

0790 

0791 

1430 

0792 

0793 

0794 

0795 

0796 

0797 

0798 

0799 

1440 

0800 

0801 

0802 

0803 

0804 

0805 

0806 

0807 

1450 

0808 

0809 

0810 

0811 

0812 

0813 

0814 

0815 

1460 

0816 

0817 

0818 

0819 

0820 

0821 

0822 

0823 

1470 

0824 

0825 

0826 

0827 

0828 

0829 

0830 

0831 

1500 

0832 

0833 

0834 

0835 

0836 

0837 

0838 

0839 

1510 

0840 

0841 

0842 

0843 

0844 

0845 

0846 

0847 

1520 

0848 

0849 

0850 

0851 

0852 

0853 

0854 

0855 

1530 

0856 

0857 

0858 

0859 

0860 

0861 

0862 

086 j 

1540 

0864 

0865 

0866 

0867 

0868 

0869 

0870 

0871 

1550 

0872 

0873 

0874 

0875 

0876 

0877 

0878 

0879 

1560 

0880 

0881 

0882 

0883 

0884 

0885 

0886 

0887 

1570 

0888 

0889 

0890 

0891 

0892 

0893 

0894 

0895 

1600 

0896 

0897 

0898 

0899 

0900 

0901 

0902 

0903 

1610 

0904 

0905 

0906 

0907 

0908 

0909 

0910 

0911 

1620 

0912 

0913 

0914 

0915 

0916 

0917 

0918 

0919 

1630 

0920 

0921 

0922 

0923 

0924 

0925 

0926 

0927 

1640 

0928 

0929 

0930 

0931 

0932 

0933 

0934 

0935 

1650 

0936 

0937 

0938 

0939 

0940 

0941 

0942 

0943 

1660 

0944 

0945 

0946 

0947 

0948 

0949 

0950 

0951 

1670 

0952 

0953 

0954 

0955 

0956 

0957 

0958 

0959 

1700 

0960 

0961 

0962 

0963 

0964 

0965 

0966 

0967 

1710 

0968 

0969 

0970 

0971 

0972 

0973 

0974 

0975 

1720 

0976 

0977 

0978 

0979 

0980 

0981 

0982 

0983 

1730 

098 4 

0985 

0986 

0987 

0988 

0989 

0990 

0991 

1740 

0992 

0993 

0994 

0995 

0996 

0997 

0998 

0999 

1750 

1000 

1001 

1002 

1003 

1004 

1005 

1006 

1007 

1760 

1008 

1009 

1010 

1011 

1012 

1013 

1014 

1015 

1770 

1016 

1017 

1018 

1019 

1020 

1021 

'022 

1023 


C-25 


January 1976 









































MACRO Assembler, Instruction, and Character Code Summaries 


2000 i 1024 
to to 

2777 1535 

(Octal) I (Decimal) 


Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 


Decimal 
4096 
8192 
12288 
16384 
•20480 
24576 
•28672 


2000 

2010 

2020 

2030 

2040 

20S0 

2040 

2070 

2100 
2110 
2120 
2130 
2140 
2 ISO 
2160 
2170 

2200 

2210 

2220 

2230 

2240 

22SO 

2260 

2270 

2300 

2310 

2320 

2330 

2340 

23SO 

2360 

2370 


1024 1025 
1032 1033 
1040 1041 
1048 1049 
1056 1057 
1064 1065 
1072 1073 
1080 1081 

1088 1089 
1096 1097 
1104 1105 
1112 1113 
1120 1121 
1128 1129 
1136 1137 
1144 1145 


1026 1027 1028 
1034 1035 1036 
1042 1 043 1 044 
1050 1051 1052 
1056 1059 1060 
1066 1067 1068 
1074 1075 1076 
1082 1083 1084 

1090 1091 1092 
1098 1099 1100 
1106 1107 1108 
1114 1115 1116 
1122 1123 1124 
1130 1131 1132 
1138 1139 1140 
IMG 1147 1148 


1029 1030 1031 
1037 1038 1039 
1045 1046 1047 
1053 1054 1055 
1061 1062 1063 
1069 1070 1071 
1077 1078 1079 
1085 1 086 1087 


1093 1 094 1 095 
1101 1102 1103 
1109 1110 1111 
1117 1118 1119 
1125 1126 1127 
1133 1134 1135 
1141 1142 1143 
1149 1150 1151 


1152 1 153 1154 1155 1156 1157 
1160 1161 1162 1163 1164 1165 
1168 1169 1170 1171 1172 1173 
1176 1177 1178 1179 1180 1181 


1184 1185 1186 118? 
1192 1193 1194 1195 
1200 1201 1202 1203 
1208 1209 1210 1211 


1216 1217 
1224 1225 
1232 1233 
1240 1241 
1248 1249 
1256 1257 
1264 1265 
1272 1273 


1218 1219 
1226 1227 
1234 1235 
1242 1243 
1250 1251 
1258 1259 
1266 1267 
1274 1275 


1188 1189 
1196 1197 
1204 1205 
1212 1213 

1220 1221 
1228 1229 
1236 1237 
1244 1245 
1252 1253 
1260 1261 
1268 1269 
1276 1277 


1158 1159 
1166 1167 
1174 1175 
1182 1183 
1190 1191 
1198 1199 
1206 1207 
1214 1215 

1222 1223 
1230 1231 
1238 1239 
1246 1247 
1254 1255 
1262 1263 
1270 1271 
1278 1279 


2400 

2410 

2420 

2430 

2440 

2450 

2460 

2470 

2500 

2510 

2520 

2530 

2540 

2550 

2560 

2570 

2600 

2610 

2620 

2630 

2640 

2650 

2660 

2670 

2700 

2710 

2720 

2730 

2740 

2750 

2760 

2770 


1290 

1288 

1296 

1304 

1312 

1320 

1328 

1336 


1281 1292 
1289 1290 
1297 1298 
1305 1306 
1313 1314 
1321 1322 
1329 1330 
1337 1338 


1283 1284 1285 
1291 1292 1293 
1299 1300 1301 
1307 1308 1309 
1315 1316 1317 
1323 1324 1325 
1331 1332 1333 
1339 1340 1341 


1344 1 345 
1352 1353 
1360 1361 
1368 1 369 
1376 1 377 
1384 1 385 
1392 1 393 
1400 1401 

1408 1409 
1416 1417 
1424 1425 
1432 1433 
1440 1441 
1448 1449 
1456 1457 
1464 1465 

1472 1473 
1480 1481 
1488 1489 
1496 1497 
1504 1505 
1512 1513 
1520 1521 
1528 1529 


1346 1 347 
1354 1355 
1332 1363 
1370 1371 
1378 1379 
1386 1387 
1394 1395 
1402 1403 

1410 Mil 
1418 1419 
1426 1427 
1434 1435 
1442 1443 
1450 1451 
1458 1459 
1466 1467 


1348 1349 
1356 1357 
1364 1365 
1372 1373 
1380 1381 
1388 1389 
1396 1397 
1404 1405 

1412 1413 
1420 1421 
1428 1429 
1436 1437 
1444 1445 
1452 1453 
1460 1461 
1468 1469 


1286 1287 
1294 1295 
1302 1 303 
1310 1311 
1318 1319 
1326 1327 
1334 1335 
1342 1343 

1350 1351 
1358 1359 
1366 1367 
1374 1375 
1382 1383 
1390 1 391 
1398 1399 
1406 1407 

1414 1415 
1422 1423 
1430 1431 
1438 1439 
1446 1447 
1454 1455 
1462 1463 
1470 1471 


1474 1475 1476 
1482 1483 1484 
1490 1491 1492 
1498 1499 1500 
1506 1507 1508 
1514 1515 1516 
1522 1523 1524 
1530 1531 1532 


1477 1478 1479 
1485 1486 1487 
1493 14911 1495 
1501 1502 1503 
1509 1510 1511 
1517 1518 1519 
1525 1526 1527 
1533 1534 1535 


3000 

to 

3777 

(Octal) 


1536 

to 

2047 

(Decimal) 



0 

1 

2 

3 

4 

5 

6 

7 


0 

• 

2 

3 

4 

5 

6 

7 

3000 

1536 

1537 

1538 

1539 

1540 

1541 

1542 

1543 

3400 

1792 

1793 

1794 

1795 

1796 

1797 

1798 

1799 

3010 

1544 

1545 

1546 

1547 

1548 

1549 

1550 

1551 

3410 

1800 

1801 

1802 

1803 

1804 

1805 

1806 

1807 

3020 

1552 

1553 

1554 

1555 

1556 

1557 

1558 

1559 

3420 

1808 

1809 

1810 

1811 

1812 

1813 

1814 

1815 

3030 

1560 

1561 

1562 

1563 

1564 

1565 

1566 

1567 

3430 

1816 

1817 

1818 

1819 

1820 

1821 

1822 

1823 

3040 

1568 

1569 

1570 

1571 

1572 

1573 

1574 

1575 

3440 

1824 

1825 

1826 

1827 

1828 

1829 

1830 

1831 

3050 

1576 

1577 

1578 

1579 

1580 

1581 

1582 

1583 

3450 

1832 

1833 

1834 

1835 

1836 

1837 

1838 

1839 

3060 

1584 

1585 

1586 

1587 

1588 

1589 

1590 

1591 

3460 

1840 

1841 

1842 

1843 

1*844 

1845 

1846 

1847 

3070 

1592 

1593 

1594 

1595 

1596 

1597 

1598 

1599 

3470 

1848 

1849 

1850 

1851 

1852 

1853 

1854 

1855 

3100 

1600 

1601 

1602 

1603 

1604 

1605 

1606 

1607 

3500 

1856 

1857 

1858 

1859 

1860 

1861 

1862 

1863 

3110 

1608 

1609 

1610 

1611 

1612 

1613 

1614 

1615 

3510 

1864 

1865 

1866 

1867 

1868 

1869 

1870 

1871 

3120 

1616 

1617 

1618 

1619 

1620 

1621 

1622 

1623 

3520 

1872 

1873 

1874 

1875 

1876 

1877 

1878 

1879 

3130 

1624 

1625 

1626 

1627 

1628 

1629 

1630 

1631 

3530 

1880 

1881 

1882 

1883 

1884 

1885 

1866 

1887 

3140 

1632 

1633 

1634 

1635 

1636 

1637 

1638 

1639 

3540 

1888 

1889 

1890 

1891 

1892 

1893 

1894 

1895 

3150 

1640 

1641 

1642 

1643 

1644 

1645 

1646 

1647 

3550 

1896 

1897 

1898 

1899 

1900 

1901 

1902 

1903 

3160 

1648 

1649 

1650 

1651 

1652 

1653 

1 6j4 

1655 

3560 

1904 

1905 

1906 

1907 

1908 

1909 

1910 

1911 

3170 

1656 

1657 

1658 

1659 

1660 

1661 

1662 

1663 

3570 

1912 

1913 

1914 

1915 

1916 

1917 

1918 

1919 

3200 

1664 

1665 

1666 

1667 

1668 

1669 

1670 

1671 

3600 

1920 

1921 

1922 

1923 

1924 

1925 

1926 

1927 

3210 

1672 

1673 

1674 

1675 

1676 

1677 

1678 

1679 

3610 

1928 

1929 

1930 

1931 

1932 

1933 

1934 

1935 

3220 

1680 

1681 

1682 

1683 

1684 

1685 

1686 

1687 

3620 

1936 

1937 

1938 

1939 

1940 

1941 

1942 

1943 

3230 

1688 

1689 

1690 

1691 

1692 

1693 

1694 

1695 

3630 

1944 

1945 

1946 

1947 

1948 

1949 

1950 

I95t 

3240 

1696 

1697 

1698 

1699 

1700 

1701 

1702 

1703 

3640 

1952 

1953 

1954 

1955 

1956 

1957 

1958 

1959 

3250 

1704 

1705 

1706 

1707 

1708 

1709 

1710 

1711 

3650 

1960 

1961 

1962 

1963 

1964 

1965 

1966 

1967 

3260 

1712 

1713 

1714 

1715 

1716 

1717 

1718 

1719 

3660 

1968 

1969 

1970 

1971 

1972 

1973 

1974 

1975 

3270 

1720 

1721 

1722 

1723 

1724 

1725 

1726 

1727 

3670 

1976 

1977 

1978 

1979 

1980 

1981 

1982 

1983 

3300 

1728 

1729 

1730 

1731 

1732 

1733 

1734 

1735 

3700 

1984 

1985 

1986 

1987 

1988 

1989 

1990 

1991 

3310 

1736 

1737 

1738 

1739 

1740 

1741 

1742 

1743 

3710 

1992 

1993 

1994 

1995 

1996 

1997 

1998 

1999 

3320 

1744 

1745 

1746 

1747 

1748 

1749 

1750 

1751 

3720 

2000 

2001 

2002 

2003 

2004 

2005 

2006 

2007 

3330 

1752 

1753 

1754 

1755 

1756 

1757 

1758 

1759 

3730 

2008 

2009 

2010 

2011 

2012 

2013 

2014 

2015 

3340 

1760 

1761 

1762 

1763 

1764 

1765 

1766 

1767 

3740 

2016 

2017 

2018 

2019 

2020 

2021 

2022 

2025 

3350 

1768 

1769 

1770 

1771 

1772 

1773 

1774 

1775 

3? 50 

2024 

2025 

2026 

2027 

2G*e 

2029 

2030 

2031 

3360 

1776 

1777 

1778 

1779 

1780 

1761 

1762 

1783 

3760 

2032 

2033 

2034 

2035 

2036 

2037 

2038 

2039 

3370 

1784 

1785 

1786 

• 787 

1788 

1769 

1790 

1791 

3770 

2040 

2041 

2042 

2041 

2044 

2045 

2C46 

2047 


January 1976 


C-26 






























MACRO Assembler, Instruction, and Character Code Summaries 


4000 

to 

4777 

(Octal) 

Octal 

10000 

20000 

30000 

40000 

50000 

60000 

70000 


2048 

to 

2559 

(Decimal) 

Decimal 

4096 

8192 

12288 

16384 

20480 

24576 

28672 


4000 

4010 

4020 

4030 

4040 

4050 

4060 

4070 

4100 

4110 

4120 

4130 

4140 

4150 

4160 

4170 

4200 

4210 

4220 

4230 

4240 

4250 

4260 

4270 


4300 

4310 

4320 

4330 

4340 

4350 

4360 

4370 


I 


2048 

2056 

2064 

2072 

2080 

2088 

2096 

2104 


2049 2050 
2057 2058 
2065 2066 
2073 2074 
2081 2082 
2089 2090 
2097 2098 
2105 2106 


2051 

2059 

2067 

2075 

2083 

2091 

2099 

2107 


2112 2113 
2120 2121 
2128 2129 
2136 2137 
2144 2145 
2152 2153 
2160 2161 
2168 2169 

2176 2177 
2184 2185 
2192 2193 
2200 2201 
2208 2209 
2216 2217 
2224 2225 
2232 2233 


2114 2115 
2122 2123 
2130 2131 
2138 2139 
2146 2147 
2154 2155 
2162 2163 
2170 2171 

2178 2179 
2186 2187 
2194 2195 
2202 2203 
2210 2211 
2218 2219 
2226 2227 
2234 2235 


2052 2053 
2060 2061 
2068 2069 
2076 2077 
2084 2085 
2092 2093 
2100 2101 
2108 2109 

2116 2117 
2124 2125 
2132 2133 
2140 2141 
2148 2149 
2156 2157 
2164 2165 
2172 2173 

2180 2181 
2188 2189 
2196 2197 
2204 2205 
2212 2213 
2220 2221 
2228 2229 
2236 2237 


2054 2055 
2062 2063 
2070 2071 
2078 2079 
2086 2087 
2094 2095 
2102 2103 
2110 2111 


2118 

2126 

2134 

2142 

2150 

2158 

2IC6 

2174 


2119 

2127 

2135 

2143 

2151 

2159 

2167 

2175 


2182 2183 
2190 2191 
2198 2199 
2206 2207 
2214 2215 
2222 2223 
2230 2231 
2238 2239 


2240 2241 
2248 2749 
2256 2257 
2264 2265 
2272 2273 
2280 2281 
2288 2289 
2296 2297 


2242 2243 2244 
2250 2251 2252 
2258 2259 2260 
2266 2267 2268 
2274 2275 2276 
2282 2283 2284 
2290 2291 2292 
2298 2299 2300 


2245 2246 
2253 2254 
2261 2262 
2269 2270 
2277 2278 
2285 2286 
2293 2294 
2301 2302 


2247 

2255 

2263 

2271 

2279 

2287 

2295 

2303 


4400 

4410 

4420 

4430 

4440 

4450 

4460 

4470 

4500 

4510 

4520 

4530 

4540 

4550 

4560 

4570 

4600 

4610 

4620 

4630 

4640 

4650 

4660 

4670 

4700 

4710 

4720 

4730 

4740 

4750 

4760 

4770 


2304 2305 
2312 2313 
2320 2321 
2328 2329 
2336 2337 
2344 2345 
2352 2353 
2360 2361 

2368 2369 
2376 2377 
2384 2385 
2392 2393 
2400 2401 
2408 2409 
2416 2417 
2424 2425 


2306 

2314 

2322 

2330 

2338 

2346 

2354 

2362 


2307 

2315 

2323 

2331 

2339 

2347 

2355 

2363 


2308 

2316 

2324 

2332 

2340 

2348 

2355 

2364 


2309 

2317 

2325 

2333 

2341 

2349 

2357 

2365 


2310 1311 
2316 6319 
2326 2327 
2334 2335 
2342 2343 
2350 2351 
2356 2359 
2366 2367 


2370 2371 
2378 2379 
2386 2387 
2394 2395 
2402 2403 
2410 2411 
2418 2419 
2426 2427 


2372 2373 2374 
2380 2381 2382 
2388 2389 2390 
2396 2397 2398 
2404 2405 2406 
2412 2413 2414 
2420 2421 2422 
2428 2429 2430 


2375 

2363 

2391 

2399 

2407 

2415 

2423 

2431 


2432 

2440 

2448 

2456 

2464 

2472 

2480 

2488 


2433 2434 
2441 2442 
2449 2450 
2457 2458 
2465 2466 
2473 2474 
2481 2482 
2489 2490 


2435 2436 
2443 2444 
2451 2452 
2459 2460 
246? 2468 
2475 2476 
2483 2484 
2491 2492 


2437 2436 2439 
2445 2446 2447 
2453 2454 2455 
2461 2462 2463 
2469 2470 2471 
2477 2478 2479 
2485 2486 2487 
2493 2494 2495 


2496 2497 
2504 2505 
2512 2513 
2520 2521 
2528 2529 
2536 2537 
2544 2545 
2552 2553 


2498 2499 
2506 2507 
2514 2515 
2522 2523 
2530 2531 
2538 2539 
2546 2547 
2554 2555 


5000 

to 

5777 

(Octal) 


2560 

to 

3071 

(Decimal) 


5000 

5010 

5020 

5030 

5040 

5050 

5060 

5070 

5100 

5110 

5120 

5139 

5140 
5150 
5160 
5170 

5200 

5210 

5220 

5230 

5240 

5250 

5260 

5270 


2560 

2566 

2576 

2584 

2592 

2600 

2608 

2616 

2624 

2632 

2640 

2648 

2656 

2664 

2672 

2680 


2561 2562 
2569 2570 
2577 2578 
2585 2586 
2593 2594 
2601 2602 
2609 2610 
2617 2618 

2625 2626 
2633 2634 
2641 2642 
2649 2650 
2657 2658 
2665 2666 
2673 2674 
2681 2682 


2563 

2571 

2579 

2587 

2595 

2603 

2611 

2619 


2564 2565 
2572 2573 
2580 2581 
2588 2589 
2596 2597 
2604 2605 
2612 2613 
2620 2621 


2566 

2574 

2582 

2590 

2596 

2606 

2614 

2622 


2567 

2575 

2583 

2591 

2599 

2607 

2615 

2623 


2627 2628 2629 
2635 2636 2637 
2643 2644 2645 
2651 2652 2653 
2659 2660 2661 
2667 2668 2669 
2675 2676 2677 
2683 2684 2685 


2688 2689 
2696 2697 
2704 2705 
2712 2713 
2720 2721 
2728 2729 
2736 2737 
2744 2745 


2690 2691 
2698 2699 
2706 2707 
2714 2715 
2722 2723 
2730 2731 
2738 2739 
2746 2747 


2692 2693 
2700 2701 
2708 2709 
2716 2717 
2724 2725 
2732 2733 
2740 2741 
2748 2749 


2630 2631 
2638 2639 
2646 2647 
2654 2655 
2662 2663 
2670 2671 
2678 2679 
2686 2687 

2694 2695 
2702 2703 
2710 2711 
2718 2719 
2726 2727 
2734 2735 
2742 2743 
2750 2751 


2500 2501 
2508 2509 
2516 2517 
2524 2525 
2532 2533 
2540 2541 
2548 2549 
2556 2557 


2502 2503 
2510 2511 
2518 2519 
2526 2527 
2534 2535 
2542 2543 
2550 2551 
2558 2559 


5400 

5410 

5420 

5430 

5440 

5450 

5460 

5470 

5500 

5510 

5520 

5530 

5540 

5550 

5560 

5570 

5600 

5610 

5620 

5630 

5640 

5650 

5660 

5670 


1 


2816 

2824 

2832 

2840 

2848 

2856 

2864 

2872 


2817 2818 2819 
2825 2826 2827 
2833 2834 2835 
2841 2842 2843 
2849 2850 2851 
2857 2858 2859 
2865 2866 2867 
2873 2874 2875 


2820 2821 
2828 2829 
2836 2837 
2844 2845 
2852 2853 
2860 2861 
2868 2869 
?876 2877 


2822 2823 
2830 2831 
2838 2839 
2646 2847 
2854 28S8 
2662 2863 
2870 2871 
2878 2679 


2880 2881 
2888 2889 
2896 2897 
2904 2905 
2912 2913 
2920 2921 
2928 2929 
2936 2937 

2944 2945 
2952 2953 
2960 2961 
2968 2969 
2976 2977 
2934 2985 
2992 2993 
3000 3001 


2882 2883 2884 
2890 2891 2892 
2898 2899 2900 
2906 2907 2908 
2914 2915 2916 
2922 2923 2924 
2930 2931 2932 
2938 2939 2940 


2885 2886 2887 
2893 2894 2895 
2901 2902 2903 
2909 2910 2911 
2917 2916 2919 
2925 2926 2927 
2933 2934 2935 
2941 2942 2943 


2946 2947 
2954 2955 
2962 2963 
2970 297J 
2978 2979 
2986 2987 
2994 2995 
3002 3003 


2948 2949 
2956 2957 
2964 2965 
2972 2973 
2980 2981 
2988 2989 
2996 2997 
3004 3005 


2950 2951 
2958 2959 
2966 2967 
2974 2975 
2988 2963 
2990 2991 
2998 2999 
3006 3007 


5300 

5310 

5320 

5330 

5340 

5350 

5360 

5370 


2752 2753 
2760 2761 
2768 2769 
2776 2777 
2784 2785 
2792 2793 
2600 2801 
2608 2609 


2754 2755 
2762 2763 
2770 2771 
2778 2779 
2766 2787 
2794 2795 
2602 2603 
2610 2611 


2756 2757 
2764 2765 
2772 2773 
2780 2781 
2788 2789 
2796 2797 
2804 2605 
2612 2613 


2758 2759 
2766 2767 
2774 2775 
2782 2783 
2790 2791 
2798 2799 
2806 2607 
2814 2615 


5700 

5710 

5720 

5730 

5740 

5750 

5760 

5770 


3008 3009 
3016 3017 
3024 3025 
3032 3033 
3040 3041 
3048 3049 
3056 3057 
3064 3065 


3010 3011 
3018 3019 
3026 3027 
3034 3035 
3042 3043 
3050 3051 
3056 3059 
3066 3067 


3012 3013 
3020 3021 
3028 3029 
3036 3037 
3044 3045 
3052 3053 
3060 3061 
3068 3069 


3014 3015 
3022 3023 
3030 3031 
3038 3039 
3046 3047 
3054 3055 
3062 3063 
3070 3071 
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MACRO Assembler, Instruction, and Character Code Summaries 


6000 

to 

6777 

(Octal) 


Octal 

10000 

20000 

30000 

40000 

60000 

60000 

70000 


3072 

to 

3583 

(Decimal) 


Decimal 

4096 

8192 

12288 

16384 

20480 

24576 

28672 


6000 

6010 

6020 

60)0 

6040 

6050 

6060 

6070 

6100 

6110 

6120 

6130 

6140 

6150 

6160 

6170 

6200 

6210 

6220 

6230 

6240 

6250 

6260 

6270 

6300 

6310 

6320 

6330 

6340 

6350 

6360 

6370 


3072 

3060 

3066 

3096 

3104 

3112 

3120 

3128 


1 


3073 3074 
3061 3062 
3069 3090 
3097 3098 
3105 3106 
3113 3114 
3121 3122 
3129 3130 


3075 3076 
3063 3084 
3091 3092 
3099 3100 
3107 3106 
3115 3116 
3123 3124 
3131 3132 


3077 3078 
3085 3086 
3093 3094 
3101 3102 
3109 3110 
3117 3118 
3125 3126 
3133 3134 


3079 

3067 

3095 

3103 

3111 

3119 

3127 

3135 


31 36 31 37 
3144 3145 
3152 3153 
3160 3161 
3168 3169 
3176 3177 
3184 3185 
3192 3193 


3138 3139 
3146 3147 
3154 3155 
3162 3163 
3170 3171 
3178 3179 
3186 3187 
3194 3195 


3200 

3208 

3216 

3224 

3232 

3240 

3248 

3256 

3264 

3272 

3280 

3288 

3296 

3304 

3312 

3320 


3201 3202 
3209 3210 
3817 3218 
3225 3226 
3233 3234 
3241 3242 
3249 3250 
3257 3258 

3265 3266 
3273 3274 
3281 3282 
3289 3290 
3297 3298 
3305 3306 
3313 3314 
3321 3322 


3203 

3211 

3219 

3227 

3235 

3243 

3251 

3259 

3267 

3275 

3283 

3291 

3299 

3307 

3315 

3323 


3140 3141 
3148 3149 
3156 3157 
3164 3165 
3172 3173 
3180 3181 
3188 3189 
3196 3197 

3204 3205 
3212 3213 
3220 3221 
3228 3229 
3236 3237 
3244 3245 
3252 3253 
3260 3261 


3142 3143 
3150 3151 
3158 3159 
3166 3167 
3174 3175 
3182 3183 
3190 3191 
3198 3199 

3206 3207 
3214 3215 
3222 3223 
3230 3231 
3238 3239 
3246 3247 
3254 3255 
3262 3263 


3268 3269 3270 
3276 3277 3278 
3284 3285 3286 
3292 3293 3294 
3300 3301 3302 
3308 3309 3310 
3316 3317 3318 
3324 3325 3326 


3271 

3279 

3287 

3295 

3303 

3311 

3319 

3327 


7000 

to 

7777 

(Octal) 


3584 

to 

4095 

(Decimal) 


7000 

7010 

7020 

7030 

7040 

7050 

7060 

7070 

7100 

7110 

7120 

7130 

7140 

7150 

7180 

7170 

7200 

7210 

7220 

7230 

7240 

7250 

7280 



0 

1 

2 

3 

4 

5 

6 

7 

6400 

3328 

3329 

3330 

3331 

3332 

3333 

3334 

3335 

6410 

3336 

3337 

3338 

3339 

3340 

3341 

3342 

3343 

6420 

3344 

3345 

3346 

3347 

3348 

3349 

3350 

3351 

6430 

3352 

3353 

3354 

3355 

3356 

3357 

3358 

3359 

6440 

3360 

3361 

3362 

3363 

3364 

3365 

3366 

3367 

6450 

3368 

3369 

3370 

3371 

3372 

3373 

3374 

3375 

6460 

3376 

3377 

3378 

3379 

3380 

3381 

3382 

3383 

6470 

3384 

3385 

3386 

3387 

3388 

3389 

3390 

3391 

6500 

3392 

3393 

3394 

3395 

3396 

3397 

3398 

3399 

6510 

3400 

3401 

3402 

3403 

3404 

3405 

3406 

3407 

6520 

3408 

3409 

3410 

3411 

3412 

3413 

3414 

3415 

6530 

3416 

3417 

3418 

3419 

3420 

3421 

3422 

3423 

6540 

3424 

3425 

3426 

3427 

3428 

3429 

3430 

3431 

6550 

3432 

3433 

3434 

3435 

3436 

3437 

3438 

3439 

6560 

3440 

3441 

3442 

3443 

3444 

3445 

3446 

3447 

6570 

3448 

3449 

3450 

3451 

3452 

3453 

3454 

2455 

6600 

3456 

3457 

3458 

3459 

3460 

3461 

3462 

3463 

6610 

3464 

3465 

3466 

3467 

3468 

3469 

3470 

3471 

6620 

3472 

3473 

3474 

3475 

3476 

3477 

3478 

3479 

6630 

3480 

3481 

3482 

3483 

3484 

3485 

3486 

3487 

6640 

3488 

3489 

3490 

3491 

3492 

3493 

3494 

3495 

6650 

3496 

3497 

3498 

3499 

3500 

3501 

3502 

3503 

6660 

3504 

3505 

3506 

3507 

3508 

3509 

3510 

3511 

6670 

3512 

3513 

3514 

3515 

3516 

3517 

3518 

3519 

6700 

3520 

3521 

3522 

3523 

3524 

3525 

3526 

3527 

6710 

3528 

3529 

3530 

3531 

3532 

3533 

3534 

3535 

6720 

3536 

3537 

3538 

3539 

3540 

3541 

3542 

3543 

6730 

3544 

3545 

3546 

3547 

3548 

3549 

3550 

3551 

6740 

3552 

3553 

3554 

3555 

3556 

3557 

3558 

3559 

6750 

3560 

3561 

3562 

3563 

3564 

3565 

3566 

3567 

6760 

3568 

3569 

3570 

3571 

3572 

3573 

3574 

3575 

6770 

3576 

3577 

3578 

3579 

3580 

3581 

3582 

3583 


1 


2 


3584 

3592 

3600 

3608 

3616 

3624 

3632 

3640 

3648 

3656 

3664 

3672 

3680 

3688 

3696 

3704 

3712 

3720 

3726 

3736 

3744 

3752 

3760 


3585 

3593 

3601 

3609 

3617 

3625 

3633 

3641 


3586 3587 
3594 3595 
3602 3603 
3610 3611 
3618 3619 
3626 3627 
3634 3635 
3642 3643 


7270 3766 


7)00 

7310 

7)20 

7330 

7)40 

7350 

7360 

7370 


3776 

3784 

3792 

2800 

3606 

3616 

3824 

3832 


3649 3650 
3657 3658 
3665 3666 
3673 3674 
3661 3682 
3689 3690 
3697 3698 
3705 3706 

3713 3714 
3721 3722 
3629 3730 
3737 3738 
3745 3746 
3753 3754 
3761 3762 
3769 3770 

3777 3778 
3765 3766 
3793 3794 
3801 3802 
3809 3810 
3817 3818 
3825 3626 
3833 3834 


3651 

3659 

3667 

3675 

3683 

3691 

3699 

3707 


3588 

3596 

3604 

3612 

3620 

3628 

3636 

3644 

3652 

3660 

3668 

3676 

3684 

3692 

3700 

3708 


3589 

3597 

3605 

3613 

3621 

3629 

3637 

3645 

3653 

3661 

3669 

3677 

3685 

3693 

3701 

3709 


3590 3591 
3598 3599 
3606 3607 
3614 3615 
3622 3623 
3630 3631 
3638 3639 
3646 3647 

3654 3655 
3662 3663 
3670 3671 
3678 3679 
3686 3687 
3694 3695 
3702 3703 
3710 3711 


3715 3716 
3723 3724 
3731 3732 
3739 3740 
3747 3748 
3755 3758 
3763 3764 
3771 3772 

3779 3780 
3787 3788 
3795 3796 
3603 3804 
3611 3612 
3619 3820 
3627 3828 
3635 3838 


3717 3 7 l8 
3725 3726 
3733 3734 
3741 3742 
3749 3750 
3757 3758 
3765 3766 
3773 3774 


3719 

3727 

3735 

3743 

3751 

3759 

3767 

3775 


3781 3782 3783 
3789 3790 3791 
3797 3796 3799 
3805 3806 3807 
3813 3814 3815 
3821 3822 3823 
3829 3630 3831 
3837 3636 3839 


7400 

7410 

7420 

7430 

7440 

7450 

7460 

7470 

7500 

7510 

7520 

7530 

7540 

7550 

7560 

7570 

7600 

7610 

7620 

7630 

7640 

7650 

7660 

7670 

7700 

*7710 

7720 

7730 

7740 

7750 

7760 

7770 


3840 

3848 

3856 

3864 

3872 

3880 

3888 

3896 


3841 

3849 

3857 

3865 

3873 

3881 

3889 

3897 


3904 3905 
3912 3913 
3920 3921 
3928 3929 
3936 3937 
3944 3945 
3952 3953 
3960 3964 


3842 3843 
3850 3851 
3858 3859 
3866 3867 
3874 3875 
3882 3883 
3890 3891 
3898 3899 

3906 3907 
3914 3915 
3922 3923 
3930 3931 
3938 3939 
3946 3947 
3954 3955 
3962 3963 


3844 3845 
3852 3853 
3860 3861 
3868 3869 
3876 3877 
3884 3885 
3892 3893 
3900 3901 

3908 3909 
3916 3917 
3924 3925 
3932 3933 
3940 3941 
3946 3949 
3956 3957 
3964 3965 


3968 

3976 

3984 

3992 

4000 

4008 

4016 

4024 

4032 

4040 

4048 

4056 

4064 

4072 

4080 

4068 


3969 3970 
3977 3978 
3985 3986 
3993 3994 
4001 4002 
4009 4010 
4017 4018 
4025 4026 

4033 4034 
4041 4042 
4049 4050 
4057 4058 
4065 4066 
4073 4074 
4081 4082 
4069 4090 


3971 3972 
3979 3980 
3987 3988 
3995 3996 
4003 4004 
4011 4012 
4019 4020 
4027 4028 

4035 4036 

4043 4044 
4051 4052 
4059 4060 
4067 4066 
4075 4076 
4063 4064 
4091 4092 


3973 

3981 

3989 

3997 

4005 

4013 

4021 

4029 


3846 3847 
3854 3855 
3862 3863 
3870 3871 
3878 3879 
3886 3887 
3894 3895 
3902 3903 

3910 3911 
3918 3919 
3926 382? 
3934 3935 
3942 3942 
3950 3951 
3958 3959 
3966 3967 

3974 3975 
3982 3982 
3990 3991 
3998 3999 
4006 4007 
4014 4015 
1022 4023 
4030 4031 


4037 4038 4039 
4045 4046 4047 
4053 4054 4055 
4061 4062 4063 
4069 4070 4071 
4077 4078 4079 
4085 4086 4067 
4093 4094 4095 
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APPENDIX D 


SYSTEM MACRO FILE 


The following is a listing of the system macro library, SYSMAC.SML. 
This file is stored on the system device, and used by MACRO when it 
expands the programmed requests discussed in Chapter 9. 


» SYSMAC.SML—SYSTEM MACRO LIBRARY 
I FOR RTli Vac. 

I 

I DEC-11-0RSYA-E 
I 

» COPYRIGHT CC) 1970,1975 
I 

I digital equipment corporation 
I MAYNARD, MASSACHUSETTS 01754 
I 


I THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY 


ON A SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH 
I THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, 

I OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE MADE 
» AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH SYSTEM AND TO 
I ONE WHO AGREES TO THESE LICENSE TERMS. TITLE TO AND OWNERSHIP OF THE 
| SOFTWARE SHALL AT all TIMES REMAIN IN DIGITAL. 


t THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO 
I CHANGE WITHOUT NOTICE AND SHOULO NOT BE CONSTRUED 
I AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 


I digital assumes no responsibility for the use 

I OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT 
I WHICH IS NOT SUPPLIED BY DIGITAL. 

I 

» EF,JO 
I 
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SYSTEM MACRO FILE 


.MACRO ..VI.. 

...VIM 

.ENOM 

.MACRO *.V2.. . 

.MCALL ...CMl,...CM2,...CM3....CMfl 

...V2«l 

.ENOM 


.MACRO ...CMI . 

AREA,.CODE#.CHAN 


.IF NB .AREA 


• AREA,X0 


MOV 


MOVB 

i.CODE,1(0) 

.ENOC 

.IF NB .CHAN 

.IF ION 

<,CHAN>,<#0> 



CLRB 

(05 

.IFF 


MOVB 

.CHAN,(0) 

.ENOC 


,ENOC 

.ENOM 

.MACRO ...CM2 .ARC,.OFFSET,.INS 
,IIF NS «,ARG*, MOV .AR6,.OFFSET(0) 

.IIP NR «.INS*, EMT *0375 

.ENOM 


.MACRO ...CMS .CHAN,.CODE 

MOV #.C0DE**0 400,X* 

.IIP NR <,CHAN>, 8ISB .CHAN,X0 

EMT *0374 

.ENOM 


.MACRO ...CM4 .AREA,.CHAN,.BUFF,.WCNT,,8LK,,CRTN,.CODE 
.. ■ CM1 «.AREA»,«.CODE>,<.CHAN» 

...CM2 «.8LK>,2. 

...CM2 «.BUPP>,4. 

...CM2 «.WCNT>,6. 

...CM2 «.CRTN»,8.,X 
.ENOM 


.MACRO .CDFN .AREA,.ADD,.NUM 
...CM1 <.AREA>,13,,#0 
...CM2 «,ADD>,2, 

...CM2 < .NUM»,4. , X 
.ENOM 


.MACRO .CHAIN 
...CM3 ,8. 

.ENOM 

.MACRO .CHCOPV .AREA,.CHAN,.OCHAN 
...CM1 «.AREA>,tl.,<.CHAN> 

...CM2 <.OCHAN>,2,,X 
.ENOM 
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SYSTEM MACRO FILE 


.MACRO . CNTXSW .AREA,.ADO 
...CMI <.AREA>,27,,#0 
...CM3 < . ADD>,2,,X 
.ENDM 

.MACRO .CMKT .AREA..ID..TIME 


...CMi «.AREA>,19,,#0 
...CM2 <, ID>,2. 

.IF B .TIME 

.IFF 

.endc 

.ENOM 

.MACRO .CLOSE .CHAM 
.IF OF ...VI 

.IFF 

...CM3 «.CHAN>,6. 

.ENOC 

.ENOM 


CLR 4,(0) 

MOV .TIME,4.(0) 

EMT *0375 

EMT *O«lfe0+,CHAN» 


.MACRO .CSIGEN 

.IF B .CSTRING 

.IFF 

.ENOC 

.ENOM 


.DEV3PC,.DEFEXT,.CSTRING 

MOV .OEVSPC,• (6.) 

MOV .DEFEXT,»(6.) 

CLR »(6.) 

MOV .CSTRING, 

EMT *0344 


.MACRO 

.CSISPC .outspc..defext, 

.CSTRING 


MOV 

.OUTSPC,-(6.) 


MOV 

.DEFEXT,-C6.) 

.IF B 

.CSTRING 

.IFF 

CLR 

•(6.) 

.ENOC 

MOV 

.CSTRING,-(6.) 

.ENOM 

EMT 

*0345 

.MACRO 

.CSTAT .AREA,.CHAN,.ADO 


...CMI 

<,AREA*,23,,«.CHAN» 


...CM2 

.ENOM 

< • ADD* * 2•» X 


.MACRO 

• DATE 



MOV 

PF34,X0 

.ENOM 

MOV 

*0262(0),X0 
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SYSTEM MACRO FILE 


.MACRO .DELETE .AREA, .CHAN, .DEVBLK..SPF 
.IF OF ...VI 

, IIF NB «.CHAN» MOV ,CHAN,X0 

EMT *0<.AREA> 


.IFF 
. . .CMI 
...CM2 
.IF B 


«,AREA>,0.«.CHAN» 

«.0EVBLK>,2. 

, 8PF 


CLR 


.IFF 


MOV 


.ENDC 


EMT 


.ENDC 

.ENOM 


4. (0) 

.8PF,4.(0) 

*0375 


.MACRO .DEVICE .AREA,.ADO 
...CM 1 «,AR£A>,12,,#0 
...CM? <.AD0>,2, ,X 
.ENOM 


.MACRO .DSTATUS .RETSPC,.DNAME 

,HF NB <.DNAME*, MOV .DNAME.X0 

MOV .RETSPC,-(8.) 

EMT *0342 

.ENOM 


CHAN,.0EVBLK,.LEN,,8PF 
MOV ,CHAN,X0 


MACRO .ENTER 
IF OF ...VI 

.IP 8 .0EV8LK 

.IFF 

.ENDC 

IFF 


AREA,. 

CLR 
MOV 
EMT 

« , CHAN* 

MOV 
CLR 

MOV 
CLR 
EMT 

EMT 


■ ( 8 .) 

.DEVBLK,-(8.) 

*O<40+.AREA> 

•LEN,4,(0) 
4.(0) 

,8PF,8.(0) 

8 .( 0 ) 

*0375 

*0350 


...CMt <,AREA>,2., 
...CM2 «.0EVBLK>,2 


.IF NB .LEN 
.IFF 
.ENDC 

.IF NB .3PF 

.IFF 

.ENDC 

ENOe 

ENOM 

MACRO .EXIT 
ENOM 
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SYSTEM MACRO FILE 


.MACRO .FETCH ,ADD,.DNAME 
.IIF NR «.DNAME>» 


.ENDM 

.MACRO .GTIM .AREA,.ADD 
...CHI <,AREA*,17.,#0 
...CM2 «,ADD*,2.,X 
.ENQH 

.MACRO .GTJ8 .AREA,.ADD 
...CMl <.AREA*,t8,,#0 
...CM2 «,ADD*.2.,X 
.ENDM 

.MACRO .HERR 
...CM3 ,5. 

.ENDM 


MOV 

.DNAME.X0 

MOV 

.ADD,*C6.) 

EMT 

*0343 


MACRO 

.HRE8ET 

ENDM 


MACRO 

.INTEN ,PRIO,.1 

IF NB 

.PIC 


MOV 


JSR 

IFF 

JSR 

,ENOC 

.WORD 

,ENOM 



EMT *0357 

#4*054,«(fe.) 

5., #(6.)+ 

5., #*054 

*C<.RRI0*32.>»22# 


.MACRO .LOCK 
.ENOM 


EMT *0346 


.MACRO .LOOKUP .AREA 
.IF OF ...VI 
, I IF NB <.CHAN*, 


,.CHAN..DEVBLK,.SPF 

MOV , CHAN,X0 

EMT *O<20*.AREA* 


...CMl 

...CM2 

<. AREA*,l,«.CHAN* 


<.DEVBLK*,2. 


.IF B 

,SPF 

4.(0) 

CLR 

.IFF 

MOV 

•3PF.4.(0) 

.endc 

EMT 

*0375 


.ENDC 

.ENDM 


.MACRO .MFP3 

.IIF NB «,AOD*» 
.ENOM 


• ADD 

MOV ##*054,»(6.) 

ADD #*03fe2.(fe.) 

J8R 7,*# (6.) ♦ 

MOVB ffc.)+».AOO 
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SYSTEM MACRO FILE 


.MACRO ,MRKT .AREA,.TIME,.CRTN,.ID 
...CM1 <.AREA>,16.,#0 


...CM2 «.TlriE*,2. 
...CM2 <,CRTN*,4, 
...CM2 <, ID*,6 .,X 
.INOM 

.MACRO .MTR8 
.IIP NB «.AOO*. 
•IIP NB <,ADD*, 


.ENOM 


.MACRO .MWAIT 
...CMS ,R, 

.ENOM 

.MACRO .PRINT ,ADD 
•IIP NB «.AOD>, 

.ENOM 


.ADO 

CLR -(6.) 

MOVB •AOD» (6,) 

MOV ##*054,» (6,) 
AOD #*0360,(6.) 

•JSR 7.,#(6«) + 


MOV .AOD,X0 

PMT *0351 


.MACRO .PROTECT .AREA,.ADD 
...CM1 <,AREA*,25, ,#0 
...CM2 <.A00*,2,,X 
.ENOM 

.MACRO .PURGE .CHAN 
...CM3 <.CHAN>,3. 

.ENOM 


.macro ,OSET .QAOO 
.IIP NB <.QLEN>, 


.ENOM 


,.QLEN 

MOVB 

MOV 

EMT 


.QLEN,X0 
,0A00.-(6.) 
0353 


.MACRO .RCTRLO 
.ENOM 


EMT *0355 


.MACRO .RCVD .AREA,.BUFF,.WCNT 

...CM4 «.AREA*,#0I,«,buFF*,«.WCNT*,,#1,22. 


.MACRO .RCVOC .AREA,.BUFF,.WCNT,.CRTN 

< » AREA> ' #0 * < * B UF'Fw,<.WCNT*,,<.CRTN>,22. 


.MACRO .RCVDW .AREA,.BUFF,.WCNT 

...CM4 «,AREA*,#0,<.BUPF*,<.WCNT*,,#0,22, 
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SYSTEM MACRO FILE 


.1* OF ...Vi 
• HF NB «.WCNT*. 


.IFF 


I,.BUFF. 

.WCNT..BLK 

MOV 

. WCNT,X0 

MOV 

#1.-(6.) 

MOV 

.BUFF,-(6.) 

MOV 

.CHAN,-(6.) 

EMT 

*O<200+,AREA* 


...CM4 <. AREA*, «.CHAN*,«.8UFF*,«.WCNT*,<.BLK*,#1,8. 

.ENOC 

.ENOM 


‘N, .BUFF 

..WCNT..CRTN,. 

MOV 

•CRTN.X0 

MOV 

.WCNT,-(6.) 

MOV 

.BUFF,»(6.) 

MOV 

,CHAN,-C6.) 

EMT 

*O«200+,AREA* 


.IF OF ...Vi 
.IIF NB <.CRTN*, 


.IFF 

...CM4 <.AREA*,«.CHAN>,«.BUFF*,<.WCNT*,«.BLK*,«.CRTN*,8, 

• ENOC 

.ENOM 


•IF OF ...Vi 
.IIF NB <.WCNT>, 


.IFF 


N,.BUFF 

, .WCNT,.BLK 

MOV 

.WCNT.X0 

CLR 

-(8.) 

MOV 

.BUFF,-(6.) 

MOV 

.CHAN,.(6.) 

EMT 

*O<200*,AREA* 


...CM« «. AREA*, <.CHAN*,«,BUFF*,<,WCNT*,«.BLK*,#0,8. 

.ENOC 

.ENOM 

.MACRO .REGDEF 

R0«X0 

Ri*Xl 

R2*X2 

R3-X3 

R4*X4 

R5«X5 

3P*X8 

PC«X7 

.ENOM 

.MACRO .RELEASE .DEVBLK 

.IIF NB «,DEVBLK*, MOV .OEVBLK,X0 

CLR -(6.) 

EMT *0343 

.ENOM 
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SYSTEM MACRO FILE 


.MACRO .RENAME .AREA, .CHAN,.DEVBLK 
.IF OF ...VI 

,IIF NB 4 .CHAN*, MOV 

EMT 

.IFF 

...CMl «.AREA*, 4 .,«,CHAN* 

...CM 2 <,DEVBLK*, 2 , ,X 
.ENOC 
.ENOM 


CHAN,X0 

O<100*.AREA* 


.macro .reopen .AREA..CHAN,.cblk 
.IF OF ...VI 

,I IF NB <.CHAN>, MOV 

EMT 

.IFF 

...CMl <.AREA*,«*.,«.CHAN* 

...CM2 «.C8LK*,2.,X 

.ENOC 

,ENDM 

.MACRO .SaVESTaT .AREA,.CHAN,.CBLK 
.IF OF ...Vi 


.CHAN,X0 
*O«140*.AREA* 


,IIF NB < .CHAN*, 


MOV .CHAN,X0 

EMT *O<120*.AREA* 


.IFF 

...CMl <.AR£A*,5.»<.CHAN* 

...CM2 <.C8LK*,2.,X 

.ENOC 

.ENOM 

.MACRO .RSUM 
...CM3 ,2. 

.ENOM 

.MACRO .BOAT .AREA,.BUFF,.WCNT 

...CM4 «.AREA*,#«,«.BUFF*,«.WCNT*,,#1,21. 

.ENOM 

.MACRO .SDATC .AREA,.BUFF,.WCNT,.CRTN 

...CM4 <.AREA*, « 0 ,<. BUFF*,<.WCNT*,,<.CRTN*,21 
.ENOM 

.MACRO .SOATW .AREA,.BUFF,.WCNT 

...CM4 <.AREA*,#0,<.BUFF*,<.WCNT*,,#0,21. 

.ENOM 

.MACRO .SERR 
...CM3 ,4. 

.ENOM 


.MACRO .SETTOP .ADD 
.IIF NB «.AOD*, 

.ENOM 

.MACRO ,8FPA .AREA,.AOD 
...CMl 4.AREA*,24.,#0 
...CM2 <.ADD*,2,,X 
.ENOM 


MOV 

EMT 


.AOO.X0 

*0354 
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SYSTEM MACRO FILE 


.MACRO .3PFUN .AREA,.CHAN,.COOE,.BUFF,.WCNT,.BLK, 


...CM1 < .AREA>,26.,« 
...CM2 «,8LK>,2, 

. chan> 


...CM2 <»BUFF>»4» 
...CM2 «,wCNT>,fc. 

.IF MB .CODE 

MOVB 

4*0377.8.(0) 

.ENOC 

.IF B .CRTN 

MOVB 

.CODE,9.(0) 

.IFF 

CLR 

10.(0) 

.ENOC 

MOV 

.CRTN,10.(0) 


EMT 

*0375 

.ENOM 



.MACRO .SRESET 

EMT 

*0352 

.ENOM 


.MACRO .SPND 
...CM3 ,1 
.ENOM 



.MACRO .SYNCH .AREA 
.IIF NB <.AREA», 

MOV 

.AREA.X4 


MOV 

F#*054»X5 

5.,4*0324(5.) 


JSR 

.ENOM 


.MACRO .TLOCK 
...CM3 ,7. 

.ENOM 



.MACRO .TRP3ET .AREA, 
...CM! <,AREA>,3,,40 
...CM2 «,ADD»,2,,X 
.ENOM 

.ADO 


.MACRO .TTINR 

EMT 

*0340 

.ENOM 


.MACRO .TTYIN .CHAR 

EMT 

*0340 

•IIF NB «.CHAR», 

BCS 

.-2 

MOVB 

X0».CHAR 

.ENOM 

.MACRO .TTOUTR 

EMT 

*0341 

■ ENOM 



.MACRO .TTVOUT .CHAR 
•IIF NB <«CHAR>, 


.ENQM 


MOVB 

EMT 

BCS 


.CHAR.X0 

*0341 

.•2 


,CRTN 
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SYSTEM MACRO FILE 


.MACRO .TWAIT .AREA,.TIMS 
...CM1 «.AREA>,20,,#0 
...CM2 «.TIME*,2.,X 
• ENOM 


.MACRO .UNLOCK 
.ENOM 


EMT *0347 


.MACRO .WAIT .CHAN 
.IF OF ...VI 

EMT *O<2«0*.CHAN* 

.IFF 

...CMS «.CHAN>,0 

• ENOC 

.ENOM 


» ^ ^ i 


.MACRO .write 
.IF OF ...Vi 
.IIF NB <.WCNT>, 


MOV 

MOV 

MOV 

MOV 

EMT 


.WCNT.X0 

, BUFF, -£B.i 
.CHAN,•(«>.) 
*O<220*.AREA* 


i ^ C <T . « n w in *■ 

.IFF 

...CM4 <.AREA>,<.CHAN>,«.BUFF>,<.WCNT*,«.BLK*,#i,9. 
.ENOC 
.ENOM 


.MACRO .WRITW .AREA 
•IF OF ...Vi 
.IIF NB «.WCNT>, 


,.CHAN,.BUFF,.WCNT, ,BLK 

MOV .WCNT,X0 

ClR -tB.) 

MOV .BUFF,-(6.) 

MOV .CHAN, *(6.5 

FMT *O«2?0+.AREA> 


,IFP 

...CM4 <.AREA>,<.CHAN»,<.BUFF*,<.WCNT>,<.BLK»,#0,9. 

.ENOC 

.ENOM 


.MACRO .WRITC .AREA, 

.CHAN,.BUFF, 

.WCNT,.CRTN,.! 

.IF OF ...VI 



.IIF NB <.CRTN>, 

MOV 

.CRTN.X0 


MOV 

.WCNT,*(6.) 


MOV 

.BUFF,-CB.) 


MOV 

.CHAN,-£6.5 


EMT 

*O<220*.AREA* 


, ,.CM4 <.AREA>,<.CHAN>,<t.BUFF>,«.WCNT*,<.BLK>,«.CRTN*,9, 

.ENOC 

.ENOM 


January 1976 


D-10 









APPENDIX E 


PROGRAMMED REQUEST SUMMARY 


E.l PARAMETERS 

The following parameters are used as arguments in various calls. (Any 
parameters used which are not mentioned here are particular to a 
request and the appropriate section in Chapter 9 should be consulted.) 


Parameter 

.addr 

.area 

.blk 

.buff 

.chan 

.crtn 

.count 

.dblk 

. num 

.went 


Description 


an address, the meaning of which depends on 
the request being used 

a pointer to the EMT argument list 

a block number specifying the relative block 
in a file where an I/O operation is to begin 

a buffer address specifying a memory location 
into which or from which an I/O transfer is 
to be performed 

a channel number in the range 0-377 (octal) 

the entry point of a completion routine 

file number for magtape/cassette operations 

the address of a four-word RAD50 descriptor 
of the file to be opened 

a number, the value of which depends on the 
request 

a word count specifying the number of words 
to be transferred to or from the buffer 
during an I/O operation 


E.2 REQUEST SUMMARY 

Refer to Appendix D (SYSMAC.SML) to see how each macro call is 
expanded in assembly language code. 
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APPENDIX F 

BASIC/RT-11 LANGUAGE SUMMARY 


BASIC/RT-11 is a single-user conversational BASIC for use under the 
RT—11 system. While the BASIC language is one of the simplest 
computer languages to learn, it contains advanced techniques which the 
experienced programmer can use to perform more intricate manipulations 
or to express a problem more efficiently. 

BASIC/RT~11 interfaces with the RT—11 monitor to provide powerful 
sequential and random-access file capabilities and allows the user to 
save and retrieve programs from peripheral devices. BASIC/RT-11 has 
provision for alphanumeric character string I/O and string variables 
(12K or larger systems) and allows user-defined functions and assembly 
language subroutine calls from user BASIC programs. 

For details on using the BASIC language, and for instructions on 
running BASIC/RT-11, refer to the BASIC/RT-11 Language Reference 
Manual (DEC-ll-LBACA-D-D) . A summary of the BASIC/RT-11 commands and 
error messages is included here for quick reference. 


F.l BASIC/RT-11 STATEMENTS 


The following summary of BASIC statements defines the general format 
for the statement and gives a brief explanation of its use. 

CALL "function name" [(argument list)] 

Used to call assembly language user 
functions from a BASIC program. 

CHAIN"file descriptor"[LINE numberl 

Terminates execution of user program, 
loads and executes the specified program 
starting at the line number, if 
included. 


c “ se O 

DATA data list 


Closes the logical file specified. If 
no file is specified, closes all files 
which are open. 

Used in conjunction with READ to input 
data into an executing program. 
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DEF FNletter (argument)=expression 

Defines a user function to be used in 
the program (letter is any alphabetic 
letter). 

DIM variable(n), variable(n,m),variable?(n),variable?(n,m) 

Reserves space for lists and tables 
according to subscripts specified after 
variable name. 


END 


Placed at the physical end of the 
program to terminate program execution. 


FOR variable = expressionl TO expression2 STEP expression! 

Sets up a loop to be executed the 
specified number of times. 


GOSUB line number 


GO TO line number 


Used to transfer control to a specified 
line of a subroutine. 

Used to unconditionally transfer control 
to other than the next sequential line 
in the program. 


IF expression rel.op. expression!THEN l line number 

(GO TO) 


Used to conditionally transfer control 
to the specified line of the program. 


IF END #nf THEN ( line number 



^GO TO J 

Used to test for end file on 
input file #n. 

sequential 

INPUT 

list 

Used to input data from the 
keyboard or papertape reader. 

terminal 

INPUT 

#expression: list 

Inputs from a sequential 

particular device. 

file or 

[LET] 

variable=expression 

Used to assign a value to the 
variable. 

specified 

[LET] 

VFn(i)=expression 

Used to set the value of 
memory file element. 

a virtual 

NEXT 

variable 

Placed at the end of a FOR loop to 


OPEN file 


FOR 


f INPUT 
1 OUTPUT 


Y|[(b)] 

r JJ 


OPEN 


file £fOR fINPUT ^ 


^OUTPUT) J 


return control to the FOR statement. 

AS FILE #n [DOUBLE BUF] 

Opens a sequential file for input or 
output as specified. File may be of the 
form "devjfilnam.ext" or a scalar string 
variable. The number of blocks may be 
specified by b. 

[(b)] AS FILE VFnx (dimension)=string length 

Opens a virtual memory file for input or 
output. x represents the type of file: 
floating point (blank), integer (%), or 
character strings ($). File may be of 
the form "devxfil.ext" or a scalar 
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OVERLAY "file descriptor" 


PRINT list 


PRINT "text" 


string variable. The number of blocks 
may be specified by b. 

Used to overlay or merge the program 
currently in memory with a specified 
file, and continue execution. 

Used to output data to the terminal. 
The list can contain expressions or text 
strings. 

Used to print a message or a string of 
characters. 


PRINT #expression: 


expression list 

Outputs to a particular output device, 
as specified in an OPEN statement. 


PRINT TAB(x); 


Used to space to the specified column. 


RANDOMIZE 


Causes the random number generator to 
calculate different random numbers every 
time the program is run. 


READ variable list 


Used to assign the values listed in a 
DATA statement to the specified 
variables. 


REM comment 

RESTORE 


Used to insert explanatory comments into 
a BASIC program. 

Used to reset data block pointer so the 
same data can be used again. 


RESTORE #n 

RETURN 


Rewinds the input sequential file #n to 
the beginning. 

Used to return program control to the 
statement following the last GOSUB 
statement. 


Used at the logical end of the program 
to terminate execution. 


F.2 BASIC/RT-11 COMMANDS 

The following key commands halt program execution, erase characters or 
delete lines. 

K e y Explanation 

ALTMODE Deletes the entire current line. Echoes DELETED 

message (same as CTRL U). On some terminals the 
ESC key must be used. 

CTRL C Interrupts execution of a command or program and 

returns control to the RT—11 monitor. BASIC may 
be restarted without loss of the current program 
by using the monitor REENTER command. 
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CTRL 0 


CTRL U 


St°p s output to the terminal and returns BASIC to 
the READY message when program or command 
execution is completed. 


Echoes DELETED 


Deletes the entire current line, 
message (same as ALTMODE). 

(SHIFT 0) Deletes the last character typed and 
echoes a backarrow (same as RUBOUT). On VT05 or 
LA30 use the underscore (_) key. 

Sckarroi h ! s ™e t „°iK aCter tyPed “ d eohoes a 

PU " Ch ' th. 


RUBOUT 


Command 

Explanation 



CLEAR 

Sets the array and string buffers 
and zeroes. 

to 

nulls 

LIST 

Prints the user program currently 
on the terminal. 

in 

memory 

LIST line number 

LIST -line number 

LIST line number-[END] 

LIST line number-line number 




Types out the specified program line(s) 
the terminal. 


on 


LISTNH line number 
LISTNH —line number 
LISTNH line number-[END] 

LISTNH line number-line number 

Lists the lines associated with the specified 
numbers but does not print a header line. 

Does a SCRatch and sets the current program 
name to the one specified. 


NEW "filnam" 
OLD "file" 
RENAME "filnam" 


Does a SCRatch and inputs the program frorr 
the specified file. 


Changes the current program name to the one 
specified. 

REPLACE "dev:filnam.ext" 

Replaces the specified file with the current 
program. 


RUN 

RUNNH 


Executes the program in memory. 


Executes the program in memory but does not 
print a header line. 

SAVE "dev:filnam.ext" 

Outputs the program in 
specified file. 


memory as the 
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SCRatch Erases the entire storage area, 

F.3 BASIC/RT-11 FUNCTIONS 

The following functions perform standard mathematical operations in 


BASIC. 


Name 

Explanation 

ABS(X) 

Returns the absolute value of x. 

ATN(x) 

Returns the arctangent of x as an angle in radians 
in the range + or - pi/2. 

BIN(x$) 

Computes the integer value of a string of blanks 
(ignored), l's and 0's. 

COS (x) 

Returns the cosine of x radians. 

EXP(x) 

Returns the value of etx where e=2.71828. 

INT(x) 

Returns the greatest integer less than or equal to 

X. 

LOG(x) 

Returns the natural logarithm of x. 

OCT(x$) 

Computes an integer value from a string of blanks 
(ignored) and digits from 0 to 7. 

RND(x) 

Returns a random number between 0 and 1. 

SGN(x) 

Returns a value indicating the sign of x. 

SIN(x) 

Returns the sine of x radians. 

SQR(x) 

Returns the square root of x. 

TAB (x) 

Causes the terminal type head to tab to column 
number x. 


The string functions ares 


ASC(x$) 

Returns as a decimal number the seven-bit internal 
code for the one-character string (x$). 

CHR$(x) 

Generates a one-character string having the ASCII 
value of x. 

DAT$ 

Returns the current date in the format 07-MAY-73. 

LEN(x$) 

Returns the number of characters in the string 
(x$). 


POS(x$,y$,z) Searches for and returns the position of the first 
occurrence of y$ in x$ starting with the zth 
position. 
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SEG$(x$,y,z) 

Returns the string of characters in positions y 
through z in x$. 

STR$(x) 

Returns the string which represents the numeric 
value of x. 

TRM$(x$) 

Returns x$ without trailing blanks. 

VAL(x$) 

Returns the number represented by the string (x$). 


F.4 BASIC/RT-11 ERROR MESSAGES 

The information that formerly appeared in Section F.4 has now been 
incorporated into the RT-11 System Message Manual , DEC-ll-ORMEA-A-D. 
BASIC/RT-11 error messages are also found in the BASIC/RT-11 Language 
Reference Manual, DEC-ll-LBACA-D-D. 
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FORTRAN LANGUAGE SUMMARY 


FORTRAN IV is a problem-solving language designed to allow scientists 
and engineers to express mathematical operations in a familiar format. 

A FORTRAN source program is composed of a series of statements. 
Statements are usually made up of one- or two-word commands, which, 
when used in conjunction with data variables and constants, can be 
used to control proaram execution, assign values to variables and read 
and write data. The FORTRAN library contains routines to simplify 
mathematical functions such as computing sines, cosines, square roots, 
etc. The source program is translated by the FORTRAN compiler into a 
machine language program which, when linked with the FORTRAN object 
time routines, can be executed by the computer. 

This appendix describes first how to run a FORTRAN program as a 
foreground job, and then summarizes briefly the RT-11 FORTRAN IV 
language, statements, and error messages. For details, refer to the 

PDP-11 FORTRAN Language Reference Manual and the RT-ll/RSTS/E 
FORTRAN IV User's Guide. 


The FORTRAN programmer may also want to read Appendix 0 for details 
concerning the FORTRAN System Subroutine Library. SYSLIB allows the 
programmer to easily call and use the programmed requests described in 
Chapter 9. A summary of the SYSLIB library calls is in Table 0-1. 


G.l RUNNING A FORTRAN PROGRAM IN THE FOREGROUND 

Since the FORTRAN Object Time System needs work areas to perform some 
of its functions, the FRUN/N!x monitor command must be used to 
allocate the needed space when running a FORTRAN program as a 
foreground job. The following formula cam be used to calculate the 
decimal number (x) which must be designated to the /N option: 

x = 1/2 [378 + (29*N) + (R-136) + A*512) ] 

where: 

N = the value of the /N FORTRAN compiler switch option (the 

compiler defaults this to 6 ) • 

R « the value of the /R FORTRAN compiler switch option (the 

compiler defaults this to 210 octal, 136 decimal). 
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A « the number of I/O buffers in simultaneous use during 
execution. (Console terminal I/O does not require any 
buffers. Each open logical unit typically requires one 
buffer.) 

For example, to calculate x for a program (FILENA.REL) which uses only 
terminal I/O and allows the compiler to assign the standard defaults, 
set the formula as follows (all values are decimal): 

x = 1/2 [378 + (29*6) + (136-136) + (0*512) ] 

276 decimal words are required. The FORTRAN program is executed using 
the FRUN command as shown: 

.FRUN FILENA.REL/N!276 <CR> 


NOTE 

An exception can occur if the size of 
the linked FORTRAN program is less than 
the size of the USR (2K) and the USR is 
to be swapped. In this case, additional 
space must be allocated to allow the USR 
to successfully swap over the linked 
FORTRAN program. The additional space 
needed may be calculated by subtracting 
the size of the linked FORTRAN program 
from 10000 octal bytes (the size of the 
USR) and adding this result to the value 
of x previously calculated. 


G.2 FORTRAN CHARACTER SET 

The characters that may appear in a FORTRAN statement are restricted 
to those listed below. 

1. The letters A through Z 

2. The numerals 0 through 9 

3. The following "special" characters: 

Character Name 

Space or Blank 
= Equals 

+ Plus 

Minus 
Asterisk 
Slash 


/ 

( 
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) Right Parenthesis 

, Comma 

. Decimal Point 

, Apostrophe 

" Double Quote 

$ Dollar Sign 

Other printable characters may appear in a FORTRAN statement only as 
part of a Hollerith constant or alphanumeric literal. Any printable 
character may appear in a comment. 


G. 3 EXPRESSION OPERATORS 

Each group of operators is shown in order of descending precedence 
during execution. 


Type 


Arithmetic 


** 

*,/ 


+ 


Relational 


.GT. 

.GE. 

.LT. 

.LE. 

.EQ. 

.NE. 

Logical 

.NOT. 


.AND. 


.OR. 


Operator 


exponentiation 
multiplication, 
division, 

addition, subtraction 
unary minus 


greater than 
greater them or 
equal to 
less them 
less them or 
equal to 
equal to 
not equal to 


.NOT.A is true if and 
only if A is false, 
and is false if A is 
true. 


A.AND.B is true if 
and only if A and B 
cure both true and is 
false if either A or 
B is false. 

A.OR.B is true if and 
only if either A or 


Operates Upon 


numeric constants, 
variables and 
expressions 


variables, 
constants, 
and arithmetic 
expressions (all 
relational operators 
have equal priority) 


logical variables, 
logical constants, 
integer variables 
and constants, logical 
integers and expressions 
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B or both A and B 
are true, and false 
If both A and B 
are false. 

.EQV. A.EQV.B is true if and 

only if A and B 
are both true or if A 
and B are both false. 

.XOR. A.XOR.B is true if and only 

if A is true and B is 
false or if B is true 
and A is false. 


G.4 SUMMARY OF FORTRAN STATEMENTS 

The following is a summary of statements available in the PDP-11 
FORTRAN IV language, including the general format for the statement 
and its effect. 


Statement Formats 


Effect 


Arithmetic/Logical Assignment 
variable=expression 


The value of the arithmetic or 
logical expression is assigned 
to the variable. 


Arithmetic Statement Functions 

name(varl,var2,...)^expression Creates a user-defined 

function having the variables 
(var) as dummy arguments. 
When referenced, the 

expression is evaluated using 
the actual arguments in the 
function call. 


ACCEPT 

ACCEPT f,list 


ASSIGN 

ASSIGN n TO ivar 


Reads input from logical unit 
5 (TTs is default); f is the 
format statement label and 
list is an optional data list. 


Assigns the statement number n 
to the integer variable ivar. 
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BACKSPACE u 


BLOCK DATA 

BLOCK DATA 

CALL 


The currently open file on 
logical unit number u is 
backspaced one record. 


Specifies the subprogram which 
follows as a BLOCK DATA 
subprogram. 



CALL name 

CALL name (argl, arg2,...) Calls the SUBROUTINE 

subprogram with the name 
specified, passing the actual 
arguments (arg) to replace the 
dummy arguments in the 
SUBROUTINE definition. 



COMMON 

COMMON/name1/var1, var2,. ../namel/var(j),var(k) 

Reserves one or more blocks of 
storage space under the name 
specified to contain the 
variables (var) associated 
with that block name. 

CONTINUE 

CONTI,iuE Causes no processing. 

DATA 

DATA varl, var2,.../vail, val2,.../ 

Causes elements in the list of 
values (val) to be initially 
stored in the corresponding 
elements of the list of 
variable names (var). 

DECODE 


Changes the elements in the 
list of variables from ASCII 
into the desired internal 
format; c is the number of 
characters, f is the format, 
v is the name of an array. 


DECODE (c,f,v)list 
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DEFINE FILE 

DEFINE FILE u(m,n,U,lvar),... 


DIMENSION 

DIMENSION sl,s2,...,sk 


DO 

DO n lvar = el,e2,e3 


END 

END 

ENCODE 

ENCODE (c,f,v)list 


END FILE 

END FILE U 


Defines the record structure 
of a disk or DECtape direct 
access file where u is the 
logical unit number, m is the 
number of fixed length records 
in the file, n is the length 
in words of a single record, U 
is a fixed argument, and lvar 
is the associated variable 
pointing to the next record. 


Reserves storage space for the 
specified array(s). Each s 
consists of an array variable 
name followed by up to seven 
integer constants, separated 
by commas and enclosed in 
parentheses. 


1. Sets integer variable ivar 
= to expression (el, e2, 
e3 must result in an 
integer quantity) 

2. Executes statements 
through statement number n 

3. Increments lvar = lvar+e3 

4. If e3>0 and ivar <=e2, or 
e3<0 and ivar >=e2, goes 
back to 2 above 


Delimits a program unit. 


Changes the elements in the 
list of variables into ASCII 
format; c is the number of 
characters in the buffer, f is 
the format statement number, 
and v is the name of the array 
to be used as the resulting 
buffer. 


The file currently open on 
logical unit number u is 
closed. 
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EQUIVALENCE 

EQUIVALENCE (varl,var2,.. 


EXTERNAL 

EXTERNAL namel,name2,... 


),(varj,vark,...) 

Each of the variables within a 
set of parentheses is assigned 
the same storage location. 


Informs the system that the 
names specified are those of 
FUNCTION or SUBROUTINE 
subprograms. 


FIND 


FIND(u'r) 


Positions the direct access 
file on logical unit number u 
to record r and sets the 
associated variable to record 
number r. 


FORMAT 

n FORMAT(field specification,...) 


Describes the format in which 
one or more records are to be 
transmitted; the statement 
number n must be specified 
(the field specifications may 
include the field descriptors, 
I, 0, F, E, D, G, L, A, H, X, 
T, Q, and $, delimited by 
field separators , and /). 


FUNCTION 

FUNCTION name 

FUNCTION name (varl,var2,...) 
type FUNCTION name (varl,var2,...) 

Begins a FUNCTION subprogram, 
indicating the program name 
and any dummy variable names 
(var). An optional type 
specification can be included. 


GOTO 

Unconditional 


GOTO n 


Transfers control to statement 
number n. 
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Computed 

GOTO (kl,k2,...,kn),e 


Assigned 


GOTO ivar 

GOTO ivar,(kl,k2,...,kn) 


Transfers control to the 
statement number ki where i = 
value of expression e. If e<l 
or e>n no transfer takes 
place. 


Transfers control to the 
statement most recently 
associated with ivar by an 
ASSIGN statement. 


IF 

Arithmetic 


IF (expression) nl,n2,n3 


Logical 

IF (expression) statement 


IMPLICIT 

IMPLICIT type (al,bl-b2,...),... 


PAUSE 


Transfers control to statement 
number n depending upon the 
value of the expression, if 
the value of the expression is 
less than zero, transfers to 
nl? if the value of the 
expression is equal to zero, 
transfers to n2, if the value 
of the expression is greater 
than zero, transfers to n3. 


Executes the statement if the 
logical expression tests true. 


The elements a and b represent 
single (or a range of) 
letter(s) whose presence as 
the initial letter of a 
variable specifies the 
variable to be of that type, 
f that variable is not 
explicitly given a type. 


PAUSE 

PAUSE display 


Suspends program execution and 
P r ^- nts the octal constant, 
Hollerith constant, or 
alphanumeric literal display, 
if one is specified. Program 
execution is resumed by typing 
a carriage return. 
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PRINT 


PRINT f,list 


READ 

Formatted 

READ(u,f) 

READ(u,f)list 
READ f,list 


Unformatted 


READ (u) 

READ(u) list 


Writes output on logical unit 
6 (LP: is default); f is the 
format statement label and 
list is an optional data list. 


Reads at least one logical 
record from device u according 
to format specification f and 
assigns values to the 
variables in the list. 
Logical unit number 1 is used 
as default in the third form 
above. 


Reads one logical record from 
device u, assigning values to 
the variables in the list. 


Direct Access 

READ(u*r)list Reads from logical unit number 

u, record number r, and 
assigns values to the 
variables in the list. 


Transfer of Control on Error 

END=n 

ERR=m 

END=n,ERR=m Optional elements in the READ 

statement list (e.g., 

READ(u,f , END=n, ERR=m) 

allowing control transfer on 
error conditions. If an 
end-of-file condition is 
detected and END=n is 
specified, execution continues 
at statement n. If a hardware 
I/O error occurs and ERR=m is 
specified, execution continues 
at statement m. 
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RETURN 


RETURN 

REWIND 

REWIND u 

STOP 

STOP 

STOP display 

SUBROUTINE 

SUBROUTINE name 

SUBROUTINE name (varl,var2,... 


Returns control to the calling 
program from the current 
subprogram. 


Logical unit number u is 
repositioned to the beginning 
of the currently opened file. 


Terminates program execution 
and prints the octal constant, 
Hollerith constant, or 
alphanumeric literal display, 
if one is specified. 


) Begins a SUBROUTINE 

subprogram, indicating the 
program name and any dummy 
variable names (var). 


Writes output on logical unit 
7 (TT: is default); f is the 
format statement label and 
list is an optional data list. 


type varl,var2,...,vark The variable names, (var), are 

assigned the specified data 
type in the program unit, 
type is one of: 

INTEGER(*2,*4) 

REAL(* 4,* 8) 

DOUBLE PRECISION 
COMPLEX(*8) 

LOGICAL(*4,*1) 

The optional * indicates that 
an explicit length is to be 
set for the variable; the 
number that follows is the 
length in bytes. The length 
must be one of the permitted 
values above. 


TYPE 

TYPE f,list 

Type Declarations 
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WRITE 

Formatted 

WRITE (u,f) 

WRITE (u,f) list 

Causes one or more logical 
records containing the values 
of the variables in the list 
to be written onto device u 
according to the format 
specification f. 


Unformatted 

WRITE (u) 
WRITE (u)list 


Direct Access 


WRITE (u'r) list 


Transfer of Control on Error 


Causes one logical record 
containing the values of the 
variables in the list to be 
written onto device u. 


Causes one logical record 
containing the values of the 
variables in the list to be 
written onto record r of the 
logical unit number u. 


END=n 

ERR=m 

END=n,ERR=m 


Optional elements in the WRITE 
statement list (e.g., WRITE 
u,f, END=n, ERR=m) allowing 
control transfer on error 
conditions. If an end-of-file 
condition is detected and 
END=n is specified, execution 
continues at statement n. If a 
hardware I/O error occurs and 
ERR=m is specified, execution 
continues at statement m. 


G.5 COMPILER ERROR DIAGNOSTICS 

The information that formerly appeared in Sections G.5 and G.6 has 

A-E> n RT-ll P P 0 RTRaM lnt ° the ■ R T ~ 11 System Message Manual , DEC-11-0RMEA- 
D. RT 11 FORTRAN error messagesarealsofoundIn the rt-II/r^t^/f 
FORTRAN IV user's Guide . DEC-ll-LRRUA-A-D. ~ H/RSTS/E 
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APPENDIX H 

F/B PROGRAMMING AND DEVICE HANDLERS 


H.l F/B PROGRAMMING IN RT-11, VERSION 2 

Certain programming conventions must be observed in RT-11, Version 2, 
which were not required in Version 1. These conventions are necessary 
to permit interrupt routines to function properly while running two 
jobs in the F/B environment. All Version 2 device handlers follow 
these conventions; the user is urged to consult the listings of the 
example handlers (Section H.3) as they illustrate some of the 
techniques discussed. 


NOTE 

Device handlers distributed with RT-11, 
Version 1 # will not work properly with 
Version 2. Also, any user-written device 
handlers should be re-written to comply 
with the Version 2 conditions. 
Instructions for interfacing new 
handlers to RT-11 are provided in the 
RT-11 Software Support Manual. 

(DEC-11—ORPGA—B—D)• Section H.2 

describes Version 2 device handlers. 


The procedures described in this appendix are necessary and must be 
followed to prevent system failures when jobs are running under RT-11. 
If at any time a program which services its own interrupts (and does 
not follow the guidelines described here) is run with another job, the 
system may malfunction. Therefore, it is required that all programs 
follow the procedures that are indicated here. 


H.1.1 Interrupt Priorities 

The status word for each interrupt vector should be set such that when 
an interrupt occurs, the processor takes it at level 7. Thus, a device 
which has its vectors at 70 and 72 has location 70 set to its service 
routine; location 72 contains 340. The 340 causes the service routine 
to be entered with the processor set to inhibit any device interrupts. 
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H.1.2 Interrupt Service Routine 

If the conventions outlined in Section H.1.1 are followed, when an 
interrupt occurs, the processor priority will be 7. The first task of 
the interrupt service routine is to lower the processor priority to 
the correct value. This can be done using the .INTEN macro call. The 
call is: 


or 


.INTEN .priority 
.INTEN .priority,.pic 


The .INTEN call is explained in Chapter 9, Programmed Requests. On 
return from the .INTEN call, the processor priority is set properly; 
registers 4 and 5 have been saved and can be used without the 
necessity of saving them again. 


For example, a user device interrupts at processor priority 5: 
DEVPRI=5 


DEVINT: .INTEN DEVPRI ;NOTE, NOT #DEVPRI 


RTS PC 

If the contents of the processor status word, loaded from the inter¬ 
rupt vector, is of significance to the interrupt service routine (e.g., 
the condition bits), the PS should be moved to a memory location (not 
the stack) before issuing the .INTEN. A device handler's interrupt 
service routine uses the monitor stack and should avoid excessive use 
of stack space. 

H.1.3 Return from Interrupt Service 

When an interrupt has been serviced, instead of issuing an RTI to 
return from the interrupt, the routine must exit with am RTS PC. This 
RTS PC returns control to the monitor, which then restores registers 4 
and 5, and executes the RTI. 

When a device handler has completed a transfer and is ready to return 
to the monitor via the internal monitor completion address, R4 must 
be pointing to the fifth word of the handler. It is no longer 
necessary to have RO and R3 on the stack, as it was in Version 1. The 
user is urged to consult the example handlers at the end of this 
appendix, which illustrates the operation of device handlers. 


H.1.4 Issuing Programmed Requests at the Interrupt Level 

Programmed requests from interrupt routines must be preceded by a 
.SYNCH call. This ensures that the proper job is running when the 
programmed request is issued. The .SYNCH call assumes that nothing 
has been pushed onto the stack by the user program between the .INTEN 
call and the .SYNCH call. On successful completion of a .SYNCH, RO 
and R1 have been saved and are free to be used. R4 and R5 are no 
longer free, and should be saved and restored if they are to be used. 

Programmed requests that require USR action should not be called from 
within interrupt routines. 80 rrom 
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H.1.5 Setting Up Interrupt Vectors 

Devices for which no RT-11 handler exists must be serviced by the user 
program* For example, no LPS device handler exists; to use an LPS, 
the user must write his own interrupt service routine. It is the 
responsibility of the program to set up the vector for devices such as 
this. The recommended procedure is not to simply move the service 
routine address and 340 into the desired vector; rather, this 
operation must be preceded by a .PROTECT macro call. The .PROTECT 
ensures that neither the other job nor the monitor already has control 
of that device. If the .PROTECT is successful, the vector can be 
initialized. 


H.1.6 Using .ASECT Directives in Relocatable Image Files 

With some exceptions, user programs in REL format should not contain 
.ASECT directives. The Linker does not allow .ASECTs above 1000 when 
the /R switch is used; in general all .ASECTs below 1000 are ignored. 
The exceptions are: 


34,36 

2 words 

TRAP instruction vector 

40 

1 word 

program start address 

42 

1 word 

stack start address 

44 

1 word 

job status word 

46 

1 word 

USR swap address 

50 

1 word 

program high limit 


•ASECTs may be used to initialize any of the above locations providing 
they are not in a program to be linked for the foreground. To initial¬ 
ize any other locations between 0-777, the user should first .PROTECT 
the appropriate words, and then move the correct values into place. 

A job which contains overlays cannot have any .ASECTs at all, 
including those listed above. If overlays are to be used, the program 
start address should be set up as the argument for the .END statement; 
the other values can be initialized when the program is initiated. 

Since .ASECTs into device vectors are not permitted, the user program 
must initialize vectors at runtime. To do this, execute a .PROTECT 
for the specified vector. If the .PROTECT is successful, it is safe 
to move values into the vectors. If the .PROTECT request fails, it is 
an indication that the vector is already in use by another job and 
that it is not safe to initialize the vector. 


H.1.7 Using .SETTOP 

Proper use of .SETTOP is vital to preserve system integrity. Since 
RT-11 employs no hardware memory protection, the user must at all 
times observe the value returned in R0 from a .SETTOP request. It 
must never be assumed that the value requested by the program is the 
value returned by .SETTOP. 
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The monitor loads foreground .programs into a memory partition just 
large enough for the program plus job header (impure area). No free 
space is available for a .SETTOP request, which may cause some pro¬ 
grams to fail, in particular, any FORTRAN program. Free space may 
be provided within the program using, for example, the .BLKW directive, 
or it may be allocated at runtime using the FRUN /N switch. Appendix 
G, Section G.l, explains how to allocate more space for FORTRAN pro¬ 
grams . 


H.1.8 Making Device Handlers Resident 

Device handlers used by a foreground job must be made permanently 
resident with a LOAD command. A .FETCH from a foreground job of a 
non-resident handler will cause a fatal error and abort the job. 
Therefore, a program written specifically for the foreground, or one 
that is to be run in either foreground or background partitions, should 
first execute a .DSTATUS on the device, to determine if the handler is 
resident, before issuing a .FETCH directive. 


H.2 DEVICE HANDLERS 

This section deals with the device handlers which are part of the 
RT-11 System, Version 2. Any device dependent information or general 
information required by the user is contained here. No mention of a 
handler implies that no special conditions must be met to use that 
device (all disks except diskette and DECtape are in this category, 
and therefore are not covered here). 
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Differences Between VI and V2 Device Handlers 

User-written device handlers must, in all cases, conform to the 
standard practices for Version 2. Since the last word of a device 
handler is used by the monitor, the user should be sure to include one 
extra word at the end of his program when indicating the size of the 
handler. 

The differences between Version 1 and Version 2 handlers include the 
followings 

A. Header Words 

In Version 1 handlers, the third header word was taken to be 
the priority at which the device interrupt was taken. In 
Version 2 , this word should be 340, indicating that the 
interrupt should be taken at priority level 7. (The priority 
level is set to 7 by the FETCH code regardless of what appears 
in the third word of the header.) 

B. Entry Conditions 

It is not necessary to save/restore registers when the 
handler is first entered, although to do so is not harmful. 
In Version 1, it was necessary to preserve R5 on first 
entering the handler. 

C. Interrupt Handling 

When an interrupt occurs. Version 2 handlers must execute an 
.INTEN request or its equivalent. (This was not necessary in 
Version 1.) On return from the .INTEN, R4 and R5 may be used 
as scratch registers. Device handlers may not do EMT 
requests without executing a .SYNCH request. (Refer to 
Chapter 9 for explanations of .INTEN and .SYNCH.) 

The handler must return from an interrupt via an RTS PC 
rather than an RTI, as in Version 1. The .INTEN request 
essentially reenters the handler via a JSR PC, and thus the 
RTS PC returns control to the monitor, which executes the RTI 
when appropriate. 

When the transfer is complete, the handler must exit to the 
monitor to terminate the transfer and/or enter a completion 
routine. When return is made to the monitor, R4 should point 
to the fifth word of the handler. 

D. Abort Entry Point 

All Version 2 device handlers must have an abort entry point 
to which control is transferred on CTRL C, hard .EXIT, or 
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.HRESET. This abort entry point is located one word before 
the interrupt service routine entry point and must contain a 
BR instruction to abort code. The abort code must stop the 
device operation and then exit through the jump into the com¬ 
pletion code in RMON. Some devices, such as moving head 
disks, cannot be effectively stopped. In this case, it is 
permissible for the abort code to consist of just an RTS PC 
instruction. Examples are the RK05 and RPR02/RP03 device 
drivers. See Section H.3 for examples of device handlers 
with abort entry code. 

The user is urged to refer to the example handlers enclosed. The same 
general techniques can be used to interface user device handlers. 


H.2.1 PR (High-Speed Paper Tape Reader) 

Unlike the PR handler for Version 1, the Version 2 PR handler does not 
print a t on the terminal when it is entered for the first time. The 
tape must be in the reader when the command is issued, or an input 
error occurs. This prohibits any two-pass operations from being done 
using PR. For example, linking and assembling from PR will not work 
properly; an input error will occur when the second pass is 
initiated. The correct (and recommended) procedure is to use PIP to 
transfer the paper tape to disk or DECtape, and then perform the 
operation on the transferred file. 


H.2.2 TT (Handler for Console Terminal) 

S'hSS! ^"iLtt 7 be “ aad as a perlph<iral devl = e *>* »*i»» <*. 


1 . 

2 . 

3. 

4. 


5. 


6 . 


7. 


A t is typed when the handler is ready for input. 

CTRL Z can be used to specify the end of input to TT. No 
carriage return is required after the CTRL Z. If CTRL Z is 

^nn^ yP f d Zi, th ? TT handler accepts characters until the word 
count of the input request is satisfied. 

CTRL O, struck while output is directed to TT, causes an 

^ t K re - OUtpU j buff< r r a11 characters currently queued) 

to be ignored. This is somewhat different than the normal 
action of CTRL 0 while at the console. 

A single CTRL C struck while typing input to TT causes a 

r^r r r -° the ?° n * tor * If out P St is directed to TO,TSo!L>le 

CTRL C is required to return to the monitor if F/B is 
running. If the S/J monitor is running, only a single CTRL C 
is required to terminate output. 

SrkLIl a S? ler . Can b6 in USe for only one job (foreground or 
background) at a time, and for only one function (input or 

output) at a time. The terminal communication for the job 
not using TT is not affected at all. 3 

The user may type ahead to TT, the input ring buffer is 

I be ty^d^aa^ refe ™“ d - T1 >* tempting 

If the main line code of a job is using TT for input, and a 
completion routine does a .TTYIN, typed characters will be 
jpassed unpredictably to the .TTYIN and TT. Therefore, this 
should not be done. ' 
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8* If a job sends a buffer to TT for output and then does a 
.TTYOUT or a •PRINT, the output from the latter is delayed 
until the handler completes its transfer. If a TT output 
operation is started when the monitor's terminal output ring 
buffer is not empty (i.e., before the print-ahead is 
complete), the handler supersedes the ring buffer until its 
transfer is complete, 

H.2,3 CR (Card Readers) 

The card reader handler can transfer data either as ASCII characters 
in DEC 026 or DEC 029 card codes (Section H,4), or as column images 
controlled by the SET command (see Chapter 2), In ASCII mode (SET CR 
NOIMAGE), invalid punch combinations are decoded as the error 
character 134(octal)—backslash. In IMAGE mode, no punch combination 
is invalid; each column is read as 12 bits of data right-justified in 
one word of the input buffer. The handler continues reading until the 
transfer word count is satisfied or until a standard end-of-file card 
is encountered (12-11-0-1-6-7-8-9 punch in column 1? the rest of the 
card is arbitrary). On end-of-file, the buffer is filled with zeroes 
and the request terminates successfully? the next input request from 
the card reader gives an end-of-file error. Note that if the transfer 
count is satisfied at a point which is not a card boundary, the next 
request continues from the middle of the card with no loss of 
information. If the input hopper is emptied before the transfer 
request is complete, the handler will loop until the hopper is 
reloaded and the "START" button on the reader is pressed again. The 
transfer will then continue until completion or until another hopper 
empty condition exists. End-of-file is not reported on the hopper 
empty condition. The handler will loop if the hopper empties during 
the transfer regardless of the status of the SET CR HANG/NOHANG 
option. No special action is required to use the card reader handler 
with the CM-11 mark sense card reader. The program should be aware of 
the fact that mark sense cards may contain less than 80 characters. 
Note also that when the CR handler is set to CRLF or TRIM and is 
reading in IMAGE mode, unpredictable results may occur. 


H.2.4 MT/CT (Magtape (TM11, TU16) and Cassette (TA11)) 

These devices have a file structure which differs from the common 
RT-11 structure. Each handler is capable of entirely supporting its 
own file structure and of allowing RT-11 users full access to the 
devices without being totally familiar with them. 


H.2.4.1 General Characteristics - Both magtape and cassette can 
operate in two possible modes: "hardware" mode and "software" mode. 
These names refer to the type of operation which can be performed on 
the device at a given time. Software mode is the normal mode of 
operation and the mode used when accessing the device through any of 
the RT-11 system programs. In software mode, the handler 
automatically attends to file headers and uses a fixed record length 
to transfer data (256-word for magtape; 64-word for cassette). 

Hardware mode allows the user to read or write any format desired, 
using any record size. In this mode, the word count is taken as the 
physical record size. 
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When the handlers are initially loaded by either the .FETCH programmed 
request or the LOAD command, only software functions are permitted. 
To switch from software to hardware mode, either a rewind or a 
nonfile-structured lookup must be performed. (A nonfile-structured 
lookup is a lookup in which the first word of the filename is null.) 

fc ^ at lf the TM1 } handler has modified (as described in the 

j^T-11 System Ge neration Manual )to one of the following: 800 BPI non¬ 
dump 7-track, 556 BPI 7-track, or 200 BPI 7-track, the handler is used 

somewhat differently. Refer to the rt- 11 System Generation Manual for 
details. - 


NOTE 

Due to the size of the TM11 and TJU16 
magtape handlers, users who have 
systems with less than 20K, and who 
have loaded both handlers simultane¬ 
ously, may experience user memory re¬ 
strictions . 


In software mode, the following functions are permitted: 


ENTER 

LOOKUP 

DELETE 

CLOSE 

READ/WRITE - 


Open new file for output 

Open existing file for input and/or output 
Delete an existing file on the device 
Close a file which was opened with ENTER or LOOKUP 
Perform data transfer requests 


In ENTER, LOOKUP, and DELETE, an optional file count parameter can be 
specified for use with magtape or cassette. Its meaning is as 
follows: 

Count Argument Meaning 

=0 A rewind is done before the operation. 

>0 No rewind is done. The value of the count is 

taken as a limit of how many files to skip before 
performing the operation (e.g., a count of 2 will 
skip over, at most, one file. A count of 1 will 
not skip at all). 

<0 A rewind is done. The absolute value of the switch 

value is then used as the limit. 

If the file indicated in the request is located before the limit is 
exhausted, the search succeeds at that point. 

As an example, consider: 



.LOOKUP 

*AREA,#0,#PT9,*5 


BCS 

• 

A1 

AREA | 

• 

• BLKW 

10. 

PTRj 

.RAD50 

/MT0/ 


.RAD50 

/EXAMPLMAC/ 


In this case, the file count argument is +5, indicating that no rewind 
is to be done and that MTO is to be searched for the indicated file 
(EXAMPL.MAC). If the file is not found after four files have been 
skipped, or if an end-of-tape occurs in that space, the search is 
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stopped, and the tape is positioned either at the end-of-tape (EOT) or 
at the start of the fifth file. If the named file is found within the 
five files, the tape is positioned at its start. If the EOT is 
encountered first, an error is generated. 

As another example: 

.LOOKUP #AREA,#0,#PTR,#-5 

This performs a rewind, and then uses a file count of five in the same 
way the above example does. 


H.2.4.2 Handler Functions 

1. LOOKUP 

If the filename (or the first word of the filename) is null, 
the operation is considered to be a nonfile-structured 
LOOKUP. This operation puts the handler into hardware mode. 
A rewind is automatically done in this case. 

If the filename is not null, the handler tries to find the 
indicated file. LOOKUP uses the optional file count as 
illustrated above. Only software functions are allowed. 


2. DELETE 

DELETE will delete a file of the indicated name from the 
device. DELETE also uses the file count argument, and can 
thus do a delete of a numbered file as well as a delete by 
name. When a file is deleted from MT or CT, an unused space 
is created there. However, it is not possible to reclaim 
that space, as it is when the device is random access. The 
unused spot will remain until the volume is re-initialized 
and rewritten. 

If a filename is not present, a nonfile-structured DELETE is 
performed and the tape is zeroed. 

3. ENTER 

ENTER creates a new file of the indicated name on the device. 
ENTER uses the optional file count, and can thus ENTER a file 
by name or by number. If ENTER by name is done, the handler 
deletes any files of the same name it finds in passing. If 
ENTER by number is done, the indicated number of files is 
skipped, and the tape is positioned at the start of the next 
file. 

NOTE 

Care must be used in performing numbered 
ENTERS, as it is possible to ENTER a 
file in the middle of existing files and 
thus destroy any files from the next 
file to the end of the tape. 

It is also possible to create more than 
one file with the same name, since ENTER 
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will only delete files of the same name 
it sees while passing down the tape. If 
an ENTER is done with a count greater 
than 0 # no rewind is performed before 
the file is entered. If a file of the 
same name is present at an earlier spot 
on the tape, the handler cannot delete 
it. A nonfile-structured ENTER 
performs the same function as a nonfile- 
structured LOOKUP but does not rewind 
the tape. Since both functions allow 
writing to the tape without regard to 
the tape's file structure, they should 
be used with care on a file-structured 
tape. 


4. CLOSE 

CLOSE terminates operations to a file on magtape or cassette 
and resets the handler to allow more LOOKUPS, ENTERS, or 
DELETES. If a CLOSE is not performed to an ENTERed file, the 
end-of-tape mark will be missing and no new files can be 
created on that volume. In this case, the last file on the 
tape must be rewritten and CLOSEd to create a valid volume. 


5. READ/WRITE 

READ and WRITE are unique in that they can be done either in 
hardware or software mode. In software mode (file opened 
with LOOKUP or ENTER), records are written in a fixed size 
(256 words for magtape, 64 words for cassette). The word 
count specified in the operation is translated to the correct 
number of records. On a READ, the user buffer is filled with 
zeroes if the word count exceeds the amount of data 
available. 

Following is a discussion of how the various parameters for 
READ/WRITE are used for magtape and cassette. 

a. Block Number 

For READ operations to magtape, the block number is 
used for random access (i.e., blocks need not be 
read sequentially from magtape). WRITE operations, 
however, disregard the block number and merely write 
the next sequential block. Block 0 on either READ 
or WRITE causes the device to rewind to the start of 
the file. A subsequent WRITE will destroy all 
previous output to that file. 

For cassette, only sequential operations are 
performed. If the block number is 0, the cassette 
is rewound to the start of the file. Any other 
block number is disregarded. 
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b. Word Count 

On a magtape READ, if the word count is 0, the block 
number is ignored and the next sequential record is 
read, no matter how big it is. 

NOTE 

Care must be taken when performing a 
magtape READ, because the READ will be 
done even if the record to be read is 
larger than the buffer allocated. 

On a magtape WRITE, if the word count is 0, one 
256-word block is written. 

If the word count for cassette is 0, the following 
conditions are possible: 

If the block number is non-zero, the operation is 
actually a file-name seek. The block number is 
interpreted as the file count argument, as discussed 
in the above example of LOOKUP. The buffer address 
should point to the RAD50 of the device and file to 
be located. This feature essentially allows an 
asynchronous LOOKUP to be performed. The standard 
LOOKUP request does not return control to the user 
program until the tape has been positioned properly, 
whereas this asynchronous version will return 
control immediately and interrupt when the file is 
positioned. 

The user may then do a synchronous, positively 
numbered LOOKUP to the file just positioned, thus 
avoiding a long synchronous search of the tape. 

If the block number is 0, a CRC (cyclical redundancy 
check) error occurs. 

Following is a description of the allowed hardware mode functions for 
the handlers, as well as examples of how to call them. In general, 
special functions are called by using the .SPFUN request; examples of 
usage follow each function. The special functions require a channel 
number as an argument. The channel must initially be opened with a 
non-file structured LOOKUP which places the handler in hardware mode. 

The general form of the .SPFUN request is: 

.SPFUN .area,.chan,.code,.buff,.went,.blk,.ertn 


where: 


.code is the function code to be performed. 
The request format is: 

R0 «> .area: 


32 


.blk 


. chan 


.buff 


.went 


.code 377 


.ertn 
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1. Magtape Special Functions 

a* Rewind (Code = 373) - Rewinds the tape to the load point. 
This puts the unit into hardware mode (as does a nonfile- 
structured LOOKUP) where any of the other functions may 
be done. 

Sample Macro Call: 

.SPFUN #A*t A, #0,#37% #0 


The above performs a synchronous rewind on channel 0 
(i.e., control will not return before the tape is 
positioned). An asynchronous rewind could be done with: 

,$HFUN *\d, , ,*CKTN ,REWIND MJ, CHANNEL 0 

where CRTN is a completion routine to be entered when the 
operation is finished. The other arguments are not 
required for this call. 


b. Write End-of-File (Code = 377) - This request writes an 
end-of-file mark, thus terminating a file. 

Sample Macro Call: 

,$HFUN #APtA,*0,#377 # *0|THIS IS THE SYNCHRONOUS FORM 

The asynchronous form is: 

.$MFUN #APfcA, «0,*?77, #0, , ,#CRTn fWRITE EOF ON 

) MT, CHANNEL 0 


c. Forward Space (Code = 376) - This function spaces forward 
the specified number of records and then stops. If the 
EOT or EOF is discovered before the count is exhausted, 
the tape stops there. Note that the number of records to 
space forward is contained in the word count argument, 
and the number passed should be the positive value of the 
desired number. 

Sample Macro Call: 

.SHFUN #APEA,#0,? SPACE FORWARD 2 

j RECORDS, CHANNEL 0 

This spaces forward two records. 


d. Back Space (Code ■ 375) - This is similar to Forward 

Space except the tape is backed up by the indicated 
number of blocks. Again, the word count must be the 
positive value of the number to back up. 


H-ll 




F/B Programming and Device Handlers 


Sample Macro Call: 

.s^fun *APtA,#0,in7S*<0 **? 

This backs the tape up by two records. 


e. Write With Extended Gap (Code = 374) - This request is 

the same as any of the WRITE requests, except that a 
longer file gap is written between records. This can be 
used to get past bad spots on the tape. 

Sample Macro Call: 

.SPFUN *AREA,#0,#374,#BUFF,#100. 

This performs a synchronous write, while: 

.SPFUN #AREA,#&,#37<l,#BUFF,#100.,#l,#CRTN 

is asynchronous and goes to CRTN when the operation is 
complete• 


f. Offline (Code = 372) - This request sets the drive to an 
off-line state. The unit cam only be set on-line by 
manual control. 

Sample Macro Call: 

.SPFUN #A»EA,#0,#37?,#0 

Since this in an instantaneous function, no asynchronous 
forms are required. 


2. Cassette Special Functions 

With exceptions noted, these requests are identical to those 

involving magtape. 

a. Rewind (Code = 373) - This request is identical to the 
rewind request for magtape, except that unless a 
completion routine is specified, control does not return 
to the user until the rewind completes. 

b. Last File (Code = 377)- This request rewinds the cassette 
and positions it immediately before the sentinel file 
(logical end-of-tape). The macro call is the same as for 
magtape code 377. 

c. Last Block (Code = 376)- This request rewinds one record. 
See the magtape code 376 for a sample macro call. 

d. Next File (Code * 375)- This request spaces the cassette 
forward to the next file. 

e. Next Block (Code = 374)- This request spaces the cassette 
forward by one record. 
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f. Write File Gap (code =372) - This request terminates a 
file written by the user program when in hardware mode. 

Sample Macro Call: 

.S^FUN 

This writes a file gap synchronously, while: 

.smiN #APtA,#e>, #T7?,#0,, ,#i 

or 

,S^FUN #APt.A,#(0,M7?,*0, , ,#CRTN 
performs asynchronous write file gap operations. 

H.2.4.3 Magtape and Cassette End-of-File Detection - Since magtape 
and cassette are sequential devices, the handlers for these devices 
cannot know in advance the number of blocks in a particular file, and 
thus cannot determine if a particular read request is attempting to 
read past the end of the file. User programs can use the following 
procedures to determine if the handlers have encountered end-of-file 
in either software or hardware mode. 

In software mode, if end-of-file is encountered, magtape and cassette 
handlers will set the end-of-file bit (bit 13) in the channel status 
word. The next read attempted on that channel wil return with the carry 
bit set and with the EMT error byte (absolute location 52) set to in¬ 
dicate an attempt to read past end-of-file. To avoid having magtape 
or cassette files appear one block longer than they really are, user 
software should check the end-of-file bit in the channel status word 
after a magtape or cassette read completes. If the bit is set, this 
indicates that the read just completed encountered end-of-file. 

The following example demonstrates the procedure in software mode: 

• MC ALL ,.va.., .REGOF-F. .GTJB , .LOOKUP,.READW 
.REGOEF 

• • V 3.. 


csweof«30000 

1 end 

OF FILE BIT IN CHANNEL STATUS WORD 

ERRWRD»53 

IEMT 

error word 

CHNL«1 

• 

• 

11 /0 

channel # 

,GTJB *Ll$T,*JOBARG 

1 GET 

JOB PARAMETERS 


•lookup’ #AREA,#CHNL,#FTLNAM ilookup magtape or cassette file 


.REAOW #AREA,#CHNL,#BUFF,#400,BLKNUM I RE AO A BLOCK 
BCS EMTERR JCHECK FOR ERROR 

MOV JOBARG+6,R1 I GET POINTER TO I/O CHANNEL SPACE 

I (CHANNEL SPACE IS 5 WORDS PER CHANNEL 
^beginning with CHANNEL 0). 

BIT *CSWEOE,CHNL*10.(R15 IIS THE EOF BIT SET FOR THIS CHANNNEL? 

BNE EOF IIF N£ - YES - EOF ENCOUNTERED ON THIS READ 
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EOF! 


iend of file code 


F1LNAMJ .Rao30 'MTP!FILNa*EXT # I0R .RAD50 'CT0FILNAMEXT' 
AREA I ,BLKW 10 

LISTI .8LKW 2 

J 08 APQI .BLKW 10 IJOB PARAMETERS STORED HERE 


In hardware mode, the cassette and magtape handlers do not report end- 
of-file, as they do in software mode. The best way that user programs 
may determine if a magtape read has encountered a tape mark or if a 
cassette read has encountered a file gap is to check the device status 
registers after each hardware mode read is complete. 


Examples are: 

For TMll/TMAll Magtape 

JTMll STATUS REGISTER 
ITM11 COMMAND REGISTER 
IE0F BIT IN MTS 
I EOT BIT IN MTS 


MTS»172520 

mtc«mts+2 

MTSEOF *40000 
MT8E0T »2000 


.READW #AREA,#CHNU.#BUFF,#«00,BlKNUM |READ A BLOCK FROM MT 


BCS 

EMTERR 

> CHECK 

ERRORS 



TST 

F#MTC 

1 ERROR 

BIT SET 

IN 

COMMAND REGISTER? 

BPL 

NOERR 

> IF PL 

- NO 



BIT 

#MTSEOF,P#MTS 

IVES - 

WAS IT 

EOF 

(TAPE MARK!? 

8NE 

EOF 

1 IF NE 

- YES - 

00 

END OF FILE PROCESSING 


EOF t IMT EOF ENCOUNTERED 


For Cassette 


T ACS*177500 

TAEOF««000 

TAEOT«20000 


»TA11 CONTROL AND STATUS REGISTER 
1 EOF BIT IN TACS 
I EOT BIT IN TACS 


•READM #AREA,#CHNL,#BUFF,#400,BLKNUM |REA0 FROM CT 


BCS 

EMTERR 

ITEST 

ERRORS 


TST 

mtacs 

i error 

BIT SET IN 

TACS? 

BPL 

NOERR 

IIF PL 

- NO 


BIT 

ftaeof.mtacs 

IVES - 

WAS IT END 

OF FILE? 

BNE 

EOF 

1 IF NE 

- YES 



EOF! 


icassette END OF FILE ENCOUNTERED 
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If desired, both the EOF and EOT bits could be checked: 

BIT #MTSEOF+MTSEOT,F#MTS IMT EOF OR EOT? 

or 

BIT #TAEOF+TAEOT,F*TAC$ »CT EOF OR EOT? 


H.2.5 DX (RX03 Diskette) 

The .SPFUN request is used to allow reading and writing of absolute 
sectors on the RX01 diskette. An RX01 disk contains 77 tracks, 
each having 26 sectors, for a total of 2002 sectors. Each sector is 
64 words long. RT-11 normally reads and writes groups of 4 sectors. 
Sectors may be accessed individually using the .SPFUN request as 
follows: 

•SPFUN .area,.chan,.code,.buff,.went,.blk,.ertn 
where: 


.code is the function code to be performed (377 for READ 
physical, 376 for WRITE physical, 375 for WRITE 
physical with deleted data mark) 

•buff is the location of a 65-word buffer; word 1 is the 

flag word and is normally set to 0 (if set to 1, 
a READ on physical sector containing deleted data 
mark is indicated); words 2-65 are the 64-word area 
to read (or write) the absolute sector 

.went is the absolute track number, 0 through 76, to be 

read (or written) 

•blk is the absolute sector number, 1 through 26, to be 

read (or written) 

The diskette should be opened with a nonfile-structured LOOKUP. Note 
also that the .buff, .went, and .blk arguments have different meanings 
when used with diskette. 

Sample Macro Call: 


.SFFUN *R"LTST,*1,#*7T # *BIJFF,*0,#?,*0 

ipfrfqrm a synchronous sfctor 

»RFA0 FROM TRACK 0, SECTOR 7 
KTHF VOLUME 10) INTO THF 
I6B-W0RD AREA RUFF 


RT-11 currently provides only one diskette handler as part of the 
system. The user may optionally install a second diskette handler by 
following the procedures outlined in Chapter 4 of the RT-11 System 
Generation Manual. - £ - 
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H.3 EXAMPLE DEVICE HANDLERS 
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,4 DEC 026/DEC 029 CARD CODE CONVERSION TABLE 


H 

Card codes in the following table are broken down by zone punch. 

Except where noted, all codes apply to both DEC 026 and DEC 029 punched 

cards. 


Table H-l 

Card Code Conversions 


Zone 

Digit 

Octal 

Character 

Name 

none 


none 

040 


SPACE 



1 

06l 

1 

digit 1 



2 

062 

2 

digit 2 



3 

063 

3 

digit 3 



i* 

064 

4 

digit 4 



5 

065 

5 

digit 5 



6 

066 

6 

digit 6 



7 

067 

7 

digit 7 

12 

(DEC 029) 

none 

046 

& 

ampersand 


(DEC 026) 


053 

+ 

plus sign 


1 

101 

A 

upper case A 



2 

102 

B 

upper case B 



3 

103 

C 

upper case C 



4 

104 

D 

upper case D 



5 

105 

E 

upper case E 



6 

106 

F 

upper case F 



7 

107 

G 

upper case G 

11 


none 

055 


minus sign 



1 

112 

J 

upper case J 



2 

113 

K 

upper case K 



3 

114 

L 

upper case L 



4 

115 

M 

upper case M 



5 

116 

N 

upper case N 



6 

117 

0 

upper case 0 

0 


7 

107 

P 

upper case P 


none 

060 

0 

digit 0 



1 

057 

/ 

slash 



2 

123 

S 

upper case S 



3 

124 

T 

upper case T 



4 

125 

U 

upper case U 



5 

126 

V 

upper case V 



6 

127 

W 

upper case W 

8 


7 

130 

X 

upper case X 


none 

70 

8 

digit 8 



1 

140 


accent grave 


(DEC 029) 
(DEC 026) 

2 

072 

137 

a- 

colon 

backarrow 

(underscore; 


(DEC 029) 

3 

043 

# 

number sign 


(continued on next page) 
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Table H-l (Cont.) 
Card Code Conversions 


Zone 

Digit 

Octal 

Character 

Name 

(DEC 026) 

(DEC 029) 
(DEC 026) 

4 

5 

075 

100 

047 

136 

@ 

t 

equal sign 
commercial "at" 
single quote 
uparrow 

(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 

9 

6 

7 

075 

047 

042 

134 

f 

n 

\ 

(circumflex) 
equal sign 
single quote 
double quote 
backslash 


none 

071 

9 

digit 9 


2 

026 

Ctrl - V 

SYN 

12-11 

7 

004 

Ctrl - D 

EOT 


none 

174 

1 

vertical bar 


1 

152 

3 

lower-case J 


2 

153 

k 

lower-case K 


3 

4 

154 

1 

lower-case L 


155 

m 

lower-case M 


5 

6 

156 

n 

lower-case N 


157 

0 

lower-case 0 

12-0 

7 

160 

P 

lower-case P 


none 

173 

{ 

open brace 


1 

l4l 

a 

lower-case A 


2 

142 

b 

lower-case B 


3 

4 

143 

c 

lower-case C 


144 

d 

lower-case D 


5 

6 

145 

e 

lower-case E 


146 

f 

lower-case F 

12-8 

7 

147 

g 

lower-case G 

(DEC 029) 
(DEC 026) 

none 

2 

110 

133 

077 

H 

C 

9 

upper-case H 
open square bracket 
question mark 

(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 

3 

4 

5 

6 

7 

056 

074 

051 

050 

135 

053 

074 

041 

< 

) 

( 

] 

+ 

< 

period 

open angle bracket 
close parenthesis 
open parenthesis 
close square bracket 
plus sign 
open angle bracket 

12-9 

j 

exclamation mark 


none 

111 

I 

upper-case I 


1 

001 

Ctrl - A 

SOH 


2 

002 

Ctrl - B 

STX 


3 

003 

Ctrl - C 

ETX 


5 

Oil 

Ctrl - I 

HT 


7 

177 


DEL 


(continued on next page) 
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Table H-l (Cont.) 
Card Code Conversions 


Zone 

Digit 

Octal 

Character 

Name 

11-0 

none 

175 

1 

close brace 


1 

176 


tilde 


2 

163 

s 

lower-case S 


3 

4 

164 

t 

lower-case T 


165 

u 

lower-case U 


5 

6 

166 

V 

lower-case V 


167 

w 

lower-case W 


7 

170 

X 

lower-case X 

11-8 

none 

121 

Q 

upper-case Q 

(DEC 029) 

2 

135 

] 

close square bracket 

(DEC 026) 

3 

4 

072 

044 

$ 

colon 

currency symbol 


052 

* 

asterisk 

(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 

5 

6 

051 

133 

073 

076 

) 

[ 

y 

> 

close parenthesis 
open square bracket 
semi-colon 
close angle bracket 

(DEC 029) 

7 

136 

+ 

uparrow 

(circumflex) 

(DEC 026) 


046 

& 

ampersand 

11-9 

none 

122 

R 

upper-case R 


1 

021 

Ctrl - Q 

DC1 


2 

022 

Ctrl - R 

DC2 


3 

023 

Ctrl - S 

DC3 


6 

010 

Ctrl - H 

BS 

0-8 

null 

131 

Y 

upper-case Y 

(DEC 029) 
(DEC 026) 

2 

134 

073 

\ 

y 

backslash 

semi-colon 

3 

4 

5 

054 

y 

comma 

(DEC 029) 
(DEC 026) 
(DEC 029) 

045 

050 

137 

% 

( 

-f- 

percent sign 
open parenthesis 
backarrow 

(underscore) 

(DEC 026) 
(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 

6 

7 

042 

076 

043 

077 

045 

IT 

> 

# 

? 

% 

double quote 
close angle bracket 
number sign 
question mark 
percent sign 

0-9 

null 

132 

z 

upper-case Z 


5 

012 

Ctrl - J 

LF 


6 

027 

Ctrl - W 

ETB 


7 

033 


ESC 

9-8 

4 

024 

Ctrl - T 

DC4 


5 

025 

Ctrl - U 

NAK 


7 

032 

Ctrl - Z 

SUB 


(continued on next page) 
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Table H-l (Cont.) 


Zone 

Digit 

Octal 

Character 

Name 

12-9-8 






3 

013 

Ctrl - K 

VT 


4 

014 

Ctrl - L 

FF 


5 

015 

Ctrl - M 

CR 


6 

016 

Ctrl - N 

SO 

11-9-8 

7 

017 

Ctrl - 0 

SI 


none 

030 

Ctrl - X 

CAN 


1 

031 

Ctrl - Y 

EM 


4 

034 

Ctrl - \ 

FS 


5 

035 

Ctrl - ] 

GS 


6 

036 

Ctrl - + 

RS 

0-9-8 

7 

037 

Ctrl - 

US 


5 

005 

Ctrl - E 

ENQ 


6 

006 

Ctrl - P 

ACK 


7 

007 

Ctrl - G 

BEL 

12-0-8 

TO n a 

none 

150 

h 

lower-case H 

12-0-9 

none 

151 

i 

lower-case I 

12-11-8 

none 

161 

q 

lower-case Q 

12-11-9 

none 

162 

r 

lower-case R 

ll-0-o 

none 

171 

y 

lower-case Y 

11- 0-9 

12- 11-9-8 

none 

172 

z 

lower-case Z 

12-0-9-8 

1 

020 

Ctrl - P 

DLE 


1 

000 


NUL 
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DUMP 


RT-11 DUMP is a program which outputs to the console or lineprinter 
all or any part of a file in octal words, octal bytes, ASCII 
characters and/or RAD50 characters, DUMP is particularly useful for 
examining data such as directories or files. 


1.1 CALLING AND USING DUMP 

DUMP is called using the monitor command: 

R DUMP 

in response to the dot printed by the Keyboard Monitor. The name of 
the file which is to be output is entered as follows in response to 
the asterisk printed by the Command String Interpreter: 

dev:output=dev:input/s 


where: 

dev: represents any valid device specification (line printer 

is default for output if no output file is designated. 
The default can be changed; refer to Chapter 4 of the 
RT-11 System Generation Manual . 

output represents the fi3.ename and extension assigned to the 
output file. The default extension for file-structured 
output is .DMP. 

input represents the input source filename and extension. 

NOTE 

Input files residing on magtape and 
cassette must have been written under 
the RT-11 system; magtape and cassette 
files written under other system 
environments cannot be dumped. 

/s represents one or more of the switches listed in Table 

1 - 1 . 

Type CTRL C to halt DUMP at any time and return control to the 
monitor. To restart DUMP type R DUMP or the REENTER command in 
response to the monitor's dot. 


1-1 
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DUMP 


1.1.1 DUMP Switches 

The following switches can appear in the command string for DUMP: 

Table 1-1 
DUMP Switches 


Switch 

Meaning 

/B 

Output octal bytes 

/E:n 

End output at block number n 

/G 

Ignore input errors 

/N 

Suppress ASCII output 

/Osn 

Output only block number n (same as /E:n, 
/S:n) 

/Ssn 

Start output with block number n 

/w 

Output octal words 

/X 

Output RAD50 characters 


If neither /W nor /B is given, /W is assumed. ASCII characters are 
always dumped unless /N is given. The number n is an octal block 
number. 


If an input filename is given, block numbers are relative to the 
beginning of the file to which the block belongs. If not, block 
numbers are absolute block numbers on the device (i.e., the physical 
block numbers on the corresponding device). 


1.1.2 Examples 

The following are two examples of DUMP. /B is used in the first 
example to output octal bytes of the file SQRT.FTN into a file called 
DIF.DMP on device DTI. 

R DUMP 

♦ DTI: DIF =SQRT. FTN/B 

If DIF.DMP is then listed on the line printer (using PIP), it appears 
as follows: 


BLOCK NUMBER 0000 


000 / 

001 

000 

096 

000 

001 

000 

911 

261 

214 

072 

190 

000 

000 

000 

001 

257 


0 

• 

• 

• 

0 

• 

0 

1 

* 

1 

M 

• 

• 

a 

• 

/ 

020/ 

224 

017 

110 

001 

000 

000 

262 

292 

304 

037 

110 

004 

210 

000 

374 

252 


0 

• 

H 

• 

• 

• 

2 

• 

D 

• 

H 

• 

• 

• 

6 

« 

040/ 

016 

024 

110 

004 

006 

000 

033 

254 

217 

163 

110 

004 

000 

000 

012 

001 


• 

• 

H 

• 

0 

• 

• 

i 

• 

$ 

H 

• 

a 

• 

• 

a 

000/ 

000 

039 

000 

001 

000 

054 

253 

100 

070 

100 

004 

000 

000 

123 

263 

024 


• 

0 

* 

• 

• 

9 

♦ 

» 

8 

#' 

• 

• 

a 

9 

3 

a 

100/ 

299 

190 

001 

000 

000 

000 

000 

000 

000 

000 

003 

000 

000 

032 

001 

000 









DUMP 


100/ 

016 

000 

064 

000 

007 

000 

000 

666 

666 

000 

666 

000 

346 

661 

000 

016 


• 

• 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

F 

a 

• 

a 

140/ 

000 

003 

060 

000 

000 

067 

011 

076 

371 

000 

000 

167 

001 

666 

614 

000 


• 

• 

• 

a 

a 

7 

a 

» 

V 

a 

a 

N 

a 

a 

• 

a 

100/ 

004 

000 

064 

006 

054 

253 

100 

070 

226 

000 

000 

000 

000 

666 

000 

000 


• 

• 

• 

• 

i 

♦ 

6 

6 

a 

a 

a 

a 

a 

• 

* 

a 

000/ 

000 

000 

060 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

666 

000 

000 


a 

• 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

t 

a 

000/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

060 

000 

000 


• 

• 

■ 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

a 

040/ 

000 

000 

060 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

* 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

060/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

066 

000 

000 


t 

• 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

a 

300/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

t 

a 

300/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

* 

* 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

340/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

600 

000 

000 


• 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

360/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

* 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

400/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

t 

t 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

400/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

■ 

t 

a 

440/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


■ 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

460/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

600 

000 

000 


a 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

* 

a 

900/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

• 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

■ 

« 

a 

520/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

a 

i 

t 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

940/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


a 

a 

• 

t 

a 

a 

a 

a 

a 

a 

a 

a 

a 

* 

• 

a 

960/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

600/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

660 

000 

000 


• 

a 

* 

■ 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

« 

a 

600/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

060 

000 

000 


• 

a 

• 

* 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

640/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

060 

000 

000 


• 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

660/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

a 

• 

t 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

700/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


a 

a 

* 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

700/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


• 

a 

• 

• 

a 

a 

a 

a 

a 

a 

a 

a 

a 

• 

• 

a 

740/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


760/ 999 999 999 000 000 000 000 000 000 000 000 000 000 000 000 000 
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The second example illustrates the use of /X to output RAD50 and 
octal values for locations in the file. The numbers in the left 
column represent the byte displacement. ASCII characters are printed 
in the far right hand column (dot represents a non-printing 


character): 









. R DUMP 









*RK1 

: L1N l( O 

. FB/X 








BLOC* 

NUMBER 

050* 








***/ 

1027k) 11 

044524 

646124 

004505 

352122 

*44514 

*45516 

0513*0 

*..title.RTLInk r* 


GNY 

K/L 

LHT 

ASM 

M8Z 

K/0 

LAB 

MEX 


020/ 

047317 

020124 

(947503 

042504 

320340 

*54*4* 

*3146* 

033453 

*00T CODE X33-1* 


11M 

LF6 

ISK 

K CL 

EEX 

NO 

MGX 

G4/ 


040/ 

006406 

035412 

05134(0 

026524 

330461 

*46040 

*47111 

0*2513 

*6.,; RT-lt LINKE* 


BOV 

XQ4 

ME* 

GJU 

G43 

LGH 

LUA 

KCS 


000/ 

006322 

035412 

042343 

041505 

030433 

*26461 

*51117 

04611* 

*R.,» DEC-U-ORLL* 


BEJ 

XQ4 

J6 

J*U 

04/ 

GII 

MF 1 

LML 


100/ 

0263(01 

0265*2 

040314 

005015 

020073 

*4*515 

*20131 

332*61 

*A.B*LA..f MAY 13* 


GlY 

gu 

JQ6 

A X M 

EFK 

JQ7 

EGA 

HTQ 


120/ 

020034 

034461 

032367 

0*5015 

020373 

*5*1*5 

*2**57 

047105 

*r 1974..; EP/ EN* 


EES 

IF A 

HNS 

AX M 

EFK 

13/ 

EE9 

LT7 


140/ 

040310 

041516 

042105 

041040 

320131 

*43512 

*05*15 

005015 

♦HANCED BY jg....* 


JU2 

J** 

J67 

J4M 

EG* 

KPJ 

AXM 

*X« 


100/ 

006473 

035412 

041443 

050117 

051131 

*43511 

*52110 

0243*0 

*;..; COPYRIGHT (* 


BOS 

1Q4 

J/X 

139 

MG* 

KPI 

MSP 

PP 2 


200/ 

024303 

024040 

034461 

*32067 

336451 

035412 

**6440 

035412 

*C) (1974)..; .,;* 


FXC 

FP2 

IP* 

HNG 

BO 1 

IQ4 

bD 

104 


220/ 

042040 

043511 

032111 

046101 

042440 

*52521 

*5*111 

042515 

* DIGITAL EQUIPME* 


J6 

API 

MSU 

LHA 

KBP 

M2 A 

L33 

KCU 


240/ 

052116 

041440 

051117 

047520 

040322 

*44524 

047117 

005015 

*NT CORPORATION..* 


MSV 

J/x 

MPl 

USX 

JRB 

K/L 

LUG 

AXM 


260/ 

02007 3 

040515 

047131 

051101 

026104 

*46440 

*515*1 

040523 

•; MAYNARD. MASSA* 


EFK 

JQ7 

LOU 

MFQ 

GCL 

LMX 

ML3 

JRC 


300/ 

044103 

051525 

352135 

051524 

030340 

*33461 

*32*65 

005013 

•CmUSETTS 31754,.* 


KVS 

mmm 

mSm 

MML 

G. 

M31 

HNE 

AXM 


320/ 

006473 

035412 

032040 

042510 

044440 

043116 

*51117 

040515 

*;..; THE INPORMA* 


BOS 

1Q 4 

MRP 

KCP 

4 • 

<X8 

MF 1 

JQ7 


340/ 

044324 

047117 

044440 

020116 

044124 

051511 

*42*4* 

041517 

*Ti0n in THIS DOC* 


K/L 

LU6 

K. 

EF* 

KV6 

MM A 

J6 

J01 


360/ 

046323 

047105 

020124 

051511 

031440 

041125 

*42512 

092133 

*UmENT is subject* 


LN7 

LT7 

EP6 

MM A 

ML 

JXU 

KCR 

MSK 


400/ 

052040 

006517 

033412 

041440 

040510 

*43516 

*2*1*5 

044527 

• to..; change mi* 


MRP 

BEG 

104 

J/X 

JQ2 

KPN 

EFU 

K/0 


420/ 

044124 

052517 

020124 

047516 

044524 

*42503 

04044* 

342116 

*thout notice and* 


KVS 

my* 

EP6 

LJV 

K/L 

KCK 

JP2 

J7P 


440/ 

031440 

047510 

046123 

020104 

047516 

*2*124 

0425*2 

041440 

« SHOULD NOT BE C* 


MU 

L $P 

UHU 

EFT 

L»V 

EF 6 

KCJ 

J/X 


460/ 

047117 

052123 

052522 

042105 

033315 

*2**73 

0515*1 

043440 

*onstrued..; as a* 


lug 

MSI 

MZB 

J57 

AXM 

EFK 

ML3 

JP2 


500/ 

041440 

*46517 

044315 

046524 

047103 

*2*124 

*545*2 

342040 

* COMNITHENT by d* 


J/X 

LNl 

K/t 

LN6 

LT7 

EF6 

NK J 

JS 


520/ 

043311 

040511 

323124 

050505 

044523 

*4652* 

*471*5 

023124 

*IGIAT EQUIPMENT * 


KPl 

JQ3 

EF6 

M E 

K/M 

LN2 

LT7 

EPS 


540/ 

047303 

050122 

051117 

052101 

347511 

*27116 

*05*15 

020073 

♦Corporation..,; * 


U>K 

L40 

Mp 1 

MSI 

L»Q 

GPN 

AXM 

EPK 


550/ 

042304 

020103 

031501 

052523 

342513 

*2*123 

*47516 

031040 

*0£C ASSUMES no R* 


KCU 

SFS 

ML3 

M*C 

KCU 

6FS 

LSV 

MEX 


600/ 

051303 

047520 

051516 

041111 

046111 

*52111 

*2*131 

047536 

•EsPONSIBILITY po* 


MU7 

L 3 X 

MMP 

JXI 

LMI 

MSG 

EGA 

LS* 


620/ 

020122 

047101 

020131 

051105 

347522 

*51522 

*52*4* 

043310 

*R ANY ERRORS THA* 


tf* 

LT3 

EG* 

MFU 

LSZ 

Mm j 

MRP 

JQ2 


640/ 

006324 

035412 

046443 

054501 

340440 

*5*12* 

*4*5*5 

023122 

*T,.; MAY APPEAR * 


BEl 

IQ4 

LMX 

NK I 

JP2 

L4 

JQ/ 

EP4 
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660/ 

e47iu 

092040 

044510 

020125 

047904 052505 

042515 

092119 

*IN THIS 

00CUMENT* 


LUA 

MRP 

K/ 

EF5 

L*L MY* 

KCU 

MSV 



700/ 

006489 

095412 

005015 

020075 

044124 051511 

051440 

043117 

*■••?••! 

THIS SOP* 


BON 

1Q4 

AXM 

EPK 

KV6 MMA 

ML 

K19 



720/ 

099824 

091101 

020105 

051611 

043040 051125 

044516 

044123 

*T«ARE is 

FURNISH* 


M86 

MFii 

fcFU 

MM A 

KM2 MF7 

x/r 

KV9 



740/ 

042105 

052040 

020117 

052520 

041522 040510 

042929 

020122 

♦ E0 TO purchaser # 


J67 

MRP 

£F1 

M2 

J04 JQ2 

KCS 

tM 



760/ 

047129 

042504 

020122 

666501 

055412 049040 

041511 

047105 

♦UnOER a. 

.1 LICEN* 


LUM 

KCL 

fcF4 

603 

104 UGH 

J0Y 

LT7 



1.2 

DUMP 

ERROR MESSAGES 






The 

following errors may occur when using 

DUMP: 





Message 



Meaning 





PIN ERR? 


A hardware error occurred 

while 






reading the input file and 

/G was 






not 

specified in 

the command 

line. 



POUT 

ERR? 


A hardware error occurred 

while 






writing an output file, or the 






output device was full 

. 




?LP NOT FND? 

A line printer 

handler is not 






available on the 

system. 
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appendix j 


filex 


J.l FILEX OVERVIEW 


9 ene f a l file transfer program used to convert files among 
devices for various operating systems. Transfers may be initiated 

PDP-n’ dS/baS^ecS^ 0 ? atl - T U directory-structured device tnt 

'* S *""** » °u tput , / •»* -SSt-So' 


"Wild-card" 

permitted. 


names (the *.* construction explained in Chapter 4) are 
Magtape and cassette are not supported in any operation. 


J.1.1 File Formats 


FILEX can transfer files created by three different ooeratina 

System/BATCH )" 1 ' nata^f, and DOS/BATCH (PDP-11 Disk Operating 
System/BATCH). Data formats that may be used in a transfer are 

ascii, image, and packed image. Because the file structure and data 
formats for each system vary somewhat, switches are needed in the 
command line to indicate the file structures and the data formats 
involved in the transfer. These switches are defined in Section 
: r^; 1 ' D ^ lces . are assumed to be in RT-11 file structure unless 
? r - /T • !Y itch (for DOS/BATCH and RSTS or DECsystem-10 

RT-11 firman fo lndlcat ® d * If b °th input and output devices are 
RTpll format (or are not file-structured), FILEX will operate like 


J.2 CALLING AND USING FILEX 


FILEX is called from the RT-11 system device by typing: 
R FILEX 


in response to the 
is printed when 
input. 


dot printed by the Keyboard Monitor. An asterisk 
FILEX is loaded and ready to accept command string 


J-l 
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FI LEX 


Type CTRL C to halt FILEX at 
monitor. To restart FILEX 
response to the monitor *s dot 


any time and return control to the 
i type R FILEX or the REENTER command in 


j.2.1 FILEX Switch Options 

Tahlo T _i Hats the switch options which are used for various FILEX 
operations. /S and /T must appear following the device and filename 

to which they apply; other switches .“jy *5?®“ e'dSSl®following 
command line. These switches are explained in more detail toliowing 

the table. 


Table J-l 

FILEX Switch Options 


Switch 


Meaning 


/A 


/D 

/F 

/I 


/I* 

/P 


/S 


Indicates a character-by-character ASCII transfer in 
which rubouts and nulls are deleted; when /T is also 
used, each PDP-10 word is assumed to contain five 7-bit 
ASCII bytes. (The transfer terminates upon reaching a 
tz for compatibility with RSTS; the tZ is not 
transferred.) 

Deletes the named file from the device; valid only for 
DOS/BATCH and RSTS DECtape. 

Causes a "fast" listing of the device directory by 
listing filenames only. 

Performs an image mode transfer; if the i" pu ^ 
either DOS/BATCH, RSTS or RT-11, this is a 

word-for-word transfer; if the input is from 
DECsvstem-10. /I indicates that the file resembles a 
file^created on DECsystem-10 by MACY11, MACXll, or 
LNKX11 with the /I switch; in this case each 

DECsystem-10 36-bit word contains one PDP-11 8-bit byte 

in its low-order bits. 

Causes a complete listing of the device directory, 
including filenames, block lengths, and creation dates, 
to appear on the console terminal. 

Performs a packed image transfer; if the input is 
either DOS/BATCH, RSTS or RT-11, this is a 

word-for-word transfer; if the input is from 
DECsystem-10, /P indicates that the file resembles a 
file created on DECsystem-10 by MACY11, MACXll, or 
LNKX11 with the /P switch, in which case each 

DECsystem-10 36-bit word contains four PDP-11 8-bit 

bytes aligned on bits 0, 8, 18, and 26 . This mode is 
assumed if no mode switch (/A, /I) is indicated m a 
command line. 

Indicates the device is a legal DOS/BATCH (or RSTS) 
block-replaceable device; the switch must appear on the 


(continued on next page) 
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FILEX 


Table J-l (Cont) 
filex Switch Options 


Switch 

_ f hr Tl •*“ Wf.B .. . . . 

Meaning 


same side of the command line as the device to which it 
applies. 

NOTE 


Neglecting to include the /S switch in a 
command line involving DOS/BATCH (or 

RSTS) causes unpredictable results. 

/T 

Indicates the device is a legal DECsystem-10 block- 
replaceable device; the switch must appear on the same 
side of the command line as the device to which it 
applies. 

/V 

Types out version number of FILEX* 

/z 

Zeroes the directory of the specified device in the 
proper format (valid only for DOS/BATCH and RSTS 
DECtape). 


j,2.2 Transferring Files Between RT—11 and DOS/BATCH (or RSTS) 


File transfers may be initiated between block-replaceable devices used 
by RT-11 and the PDP-11 DOS/BATCH system. Input from DOS/BATCH may be 
either disk or DECtape; both linked and contiguous files are supporte 
as inDut If the input device is a DOS/BATCH disk, the user should 
specify a DOS/BATCH user identification code (called a UIC; refer to 
the DOS/BATCH Handbook, DEC-11-0DBHA-A-D). This UIC then 
default for all future transfers. If no UIC is specified, the current 
default UIC is used (see the description of UIC, following). Outpu 
to DOS/BATCH is limited to DECtape only. DECtape used und<er the RSTS 
system is also legal as both input and output, since its format is 
identical to DOS/BATCH DECtape; see the PDP-11 Resource f 
Sharina System User's Guide, DEC-11-0RSUA-D-D.Any valid RT -11 file 
storage device may be used for either input or output in the transfer. 
The RT-11 device DK; is assumed if no device is indicated. 


NOTE 


An RT-11 DECtape can hold more 
information than a DOS/BATCH or RSTS 
DECtape. Thus, caution should be 
observed in copying files from a full 
RT-11 tape to a DOS DECtape as some 
information may not transfer. In such a 
case an error message will be printed 
and the transfer will not be completed. 

When a transfer from an RT-11 device to 
a DOS DECtape occurs, the block size of 
the file may increase. However, if the 
file is later transferred back to an 
RT-11 device, the block size does not 
decrease. 


To transfer a file from a legal DOS/BATCH block-replaceable device (or 
RSTS DECtape) to a legal RT-11 device, the command string format is: 
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*dev:filnam.ext=dev:filnam.ext/S/s[UIC] 


where: 

dev: 


f ilnam.ext 


/S 


/s 


[UIC] 


! on the output side, any valid RT-11 device (if 
that device is not file-structured, filnam.ext may 
be omitted); on the input side, DOS/BATCH DECtape 
or disk, or RSTS DECtape. 

' fo f output, any valid RT-11 filename and 

®^ en f lon '* f °r input, any valid DOS/BATCH 

(RSTS) filename and extension. 

the switch from Table J—1 which designates a 
DOS/BATCH (RSTS) block-replaceable device. (This 
switch MUST be included in the command line.) 

optionally any other switch (one only) from Table 
(rn this case, /A is the only meaningful 
switch which could be chosen); /A indicates an 
ASCII transfer is to be performed in which nulls 
and rubouts are deleted; if /A is not used, the 
transfer will be performed word-for-word. 

the DOS/BATCH user identification code in the 
format [nnn,nnn] where nnn represents 1 to 3 octal 
less than or equal to 377 specifying first 
the user-group number, and then the individual 
user number; this code may be placed anywhere on 
the side of the command line containing the 
DOS/BATCH device; whenever a UIC is entered, it 
becomes the default for any further DOS/BATCH 
transfers; the initial default value is [1,1], 

NOTE 

A UIC need not be indicated in any 
command line if accessing only DECtape 
since individual users do not "own" 
files on DECtape under DOS; no error 
will occur if a code is used, however. 


RSTs ranS DPr^ai« eS 4 -h r ° m an s ^ orage device to a DOS/BATCH or 

RSTS DECtape, the command line format is as follows: 


*DTn:filnam.ext/S/s=dev:filnam.ext 


where: 

DTn: 


filnam.ext 


/S 


a v * 1:L d D° s /BATCH (RSTS) DECtape assignment 
(only DECtape is legal for output). 

= for output, any valid DOS/BATCH (RSTS) filename 
and extension; for input, any valid RT-11 
filename and extension. 

= ®^ ch , from Table J-l which designates a 
DOS/BATCH (RSTS) block-replaceable device. (This 
switch MUST be included in the command line.) 
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/s = optionally any other switch (one only) from Table 

J-l (in this case, /A is the only meaningful 
switch which could be chosen)? /A indicates an 
ASCII transfer is to be performed in which nulls 
and rubouts are deleted? if /A is not used, the 
transfer will be performed word-for-word. 

dev: = any valid RT-11 device. 

Examples: 

* DT2:SORT. RBC/S=SGRT. BBC 

This command instructs FILEX to transfer a file called SORT.ABC from 
the RT-11 system device to a DOS /BATCH (or RSTS) formatted DECtape 
on unit DT2. 

*pp : =0T2:TVPE. FlL/5/ft 

This command allows a file to be transferred from DOS/BATCH (or 
RSTS DECtape to the papertape punch under RT-11. The transfer is 

done in ASCII mode. 

*DK:*. * = RK1:MfiCRl. MRC-'St 200.200 ] 

This command causes the file MACR1.MAC from the DOS/BATCH disk on unit 
1 which is stored under the OIC [200,200] to be transferred to the 
RT-11 device DK. [200,200] becomes the default UIC for any further 
DOS/BATCH operations. 


j.2.3 Transferring Files to RT-11 from DECsystem-10 

Files may be transferred to RT-11 devices from a DECsystem-10 DECtape 
whenever a foreground job is not running (this restriction is due to 
the fact that when reading DECsystem-10 files, FILEX accesses the 
DECtape control registers directly rather than using the RT-11 DECtape 
control handler). Output may be to any valid RT-11 device? 
DECsystem-10 DECtape is the only valid input device. The format of 
the command line is: 

*dev:filnam.ext=DTn:filnam.ext/T/s 


where: 


dev: = any valid RT-11 device? if that device is not 

file-structured, the filnam.ext may be omitted. 

filnam.ext = for output, any valid RT—11 filename and 

extension? for input, any valid DECsystem-10 
filename and extension (see NOTE below). 

DTn: * a valid DECsystem-10 DECtape assignment (only 

DECtape is legal for input). 

/T = the switch from Table J-l which . signifies a 

DECsystem-10 DECtape. When using /T, especially 
with /A, the time of day clock will lose time. It 
should be examined with the monitor TIME command, 
and reset if necessary. 
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/ s * any other switch from Table J-l which specifies 

the mode of transfer. Only one additional switch 
may be indicated per transfer; /P is assumed if 
no other mode is specified. 


NOTE 

RT-11 files may be indirectly converted 
to DECsystem-10 format by running RT-11 
FILEX and converting the files to DOS 
formatted DECtape, and then running 
DECsystem—10 FILEX to read the DOS 
DECtape; however, it is currently not 
possible under RT-11 to convert files 
directly from RT-11 to DECsystem-10 
format. 


Examples: 

*DT2:STAND. LI S = DT1: STAND. LIS,'T/A 

The ASCII file STAND.LIS is converted from DECsystem-10 ASCII format 
to RT-11 ASCII format and stored under RT-11 on DECtape 2 as 
STAND.LIS. * 


NOTE 

Transfers from DECsystem-10 DECtape to 
RT-11 DECtape may cause an <UNUSED> 
block to appear after the file on the 
RT-11 device. This is a result of the 
method by which RT-11 handles the 
increased amount of information on a 
DECsystem-10 DECtape. 


* S V : *. NEW=DT0:* LIS/T 

This command indicates that all files on DECsystem-10 DECtape 0 with 
the extension .LIS are to be transferred to the RT-11 system device 
(disk or DECtape) using the same filename and an extension of .NEW. 
The /P switch is the assumed transfer mode. 


J.2.4 Listing Directories 

Device directories of any of the block-replaceable devices used in a 

FILEX transfer can be listed on the console terminal. The following 
FILEX command lines are used: 


*dev:/L 


for RT-11 


*dev:/L/S for DOS/BATCH (RSTS-11) 

*DTn:/L/T for DECsystem-10 
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where: 


dev: 

ss 

disk or DECtape (DK is assumed if no device 
specified). 

is 

DTn: 

= 

DECsystem-10 DECtape. 


/L 


the switch from Table J-l which indicates 

a 


listing is desired (/F may be substituted if 
"fast listing" is preferred). 

a 


/s 

= 

the switch from Table J-l which designates 
DOS /BATCH or RSTS-11 block-replaceable device. 

a i 

/T 

ss 

the switch from Table J-l which designates 

DECsystem-10 block-replaceable device. 

a 

i 


Examples: 


*RK1: /L/5 
BRDB . SVS 
MONLIB. CIL 
DU 11 . PfiL 

VERIFY. LDfi 
CILUS . LDfi 


1 

22-JUL-74 

1 ? 5C 

22-JUL-74 

45 

24-JUL-74 

S?C 

22-JUL-74 

29 

22-JUL-74 


This command lists the complete disk directory of the device RK1. The 
letter "C" following the file size on a DOS/BATCH or RSTS directory 
listing indicates the file is a contiguous file. 


*DT1: *. PFlL/L.'S 

This command lists all files with the extension .PAL which are on 
drive 1. 


♦ DTI *. */F/T 

All files on DECsystem-10 formatted DECtape 1, regardless of filename 
or extension, are listed; a fast directory is requested (/F) in which 
only filenames are printed. 


J.2.5 Deleting Files from DOS/BATCH (RSTS) DECtapes 

FILEX may be used to delete files from, and zero directories of, 
DOS/BATCH and RSTS formatted DECtapes. The format of these command 
lines is: 

*dev:filnam.ext/S/D 
or 

*dev:/S/Z 

dev:/Z ARE YOU SURE? 

where: 

dev: = DOS/BATCH or RSTS DECtape. 

filnam.ext = a valid DOS/BATCH (RSTS) filename and 

extension. 


to delete a file 
to zero a directory 
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/ s “ the switch from Table J-l which designates that 

the device is a DOS/BATCH (RSTS) block-replaceable 
device. 


“ the switch from Table J-l which designates that a 
file is to be deleted. 

/ z " the switch from Table J-l which designates that a 

directory is to be zeroed. 

Examples: 


*DT0:*. PRL/D/S 


All files on DECtape 0 with the extension .PAL are deleted. 

*DT2:TABLE. OBJ/D/S 

The file TABLE.OBJ is deleted from the DECtape on unit 2. 

*DT0: /Z/5 

DT0./Z ARE V0U SURE ?V 

The DECtape on drive 0 is initialized in DOS/BATCH (RSTS) format so 
that it contains no files. 

J.3 FILEX ERROR MESSAGES 

Following is a list of error messages that may occur under FILEX: 


Message 


Meaning 


?filnam.ext ALREADY EXISTS? 

An attempt was made to create the named file 
(filnam.ext) on a DOS DECtape when a file 
already existed under the name specified. 
Use /D to delete the file, and retry the 
transfer. 


?BAD PPN? 


?COR OVR? 


?DEV FULL? 


?DIR ERR? 


The DOS/BATCH user identification code was 
not in the form [nnn,nnn], where each nnn is 
an octal number less than or egual to 
377(octal). 

There was insufficient main storage for 
buffers and input list expansion. Try 
copying files one at a time, without using 
the "wild-card" (*.*) construction on input. 

There was no room in the directory for the 
filename or there was no room on the output 
device for the file (in which case the 
filename is not placed in the output device 
directory). 

An error occurred while reading or looking up 
the directory of the input device, or the 
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FI LEX 


7FEATURE NOT IMP? 

?FG ACTIVE? 

?FIL NAM? 

?FIL NOT FND? 

?ILL CMD? 


?ILL DEV? 


?ILL SWT? 

?IN ERR? 
?NO UFD? 

?OUT ERR? 
?SWT ERR? 


input device does not have the proper file 
structure. 

An operation was attempted which FILEX cannot 
perform (e.g. r zeroing an RT-11 device). 

An attempt was made to use /T when a 
foreground job was active. The transfer is 
not allowed until the foreground job is 
terminated and unloaded via UNLOAD FG. 

The output filename was invalid or null. 

The input file was not found, or the 
•'wild-card" (*.*) construction matched none 
of the existing files. 

The length of the command line exceeded 72 
characters; the command line was not in 
proper CSI format? the UIC exceeded the 
allowed number of characters or [ was used 
without ]? a "wild-card" (*.*) construction 
was used on a sequential-access device? no 
output or no input file was specified for a 
copy operation, or more than one filename 
construction (devsfilnam.ext) was specified 
on either side of the = (<) sign. 

The device handler was not found, an invalid 
or illegal device name was used, or one of 
the following was attempted: 

RK or DT was not used for DOS/BATCH 
(RSTS) input in a copy operation; 

DT was not used for DOS/BATCH (RSTS) 

output in a zero or delete operation? 

DT was not used for DOS/BATCH (RSTS) 

output in a copy operation? 

DT was not used for DECsystem-10 input 
in any operation. 

An illegal switch was used in a command line 
(e.g., a switch not listed in Table J-l). 

A device error occurred on input. 

The specified UFD was not found on the DOS 
input disk. 

A device error occurred on output. 

An attempt was made to use more than one /S 
or /T switch in a command line (only one is 
allowed)? an attempt was made to use more 
than one transfer mode switch (/I f /P, /A) or 
more than one operation switch (/D, /L, /F, 

/Z) in a command line (only one of each is 
allowed). 
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APPENDIX K 

SOURCE COMPARE (SRCCOM) 


The RT-11 Source Compare program (SRCCOM) is used to compare two ASCII 
files and to output any differences to a specified output device. It 
is particularly useful when the two files are different versions of a 
single program, in which case SRCCOM prints all the editing changes 
which transpired between the two versions. 


K.l CALLING AND USING SRCCOM 
To run SRCCOM type the commands 
R SRCCOM 

followed by a carriage return in response to the dot printed by the 
Keyboard Monitor; the CSI prints an asterisk. Then enter the names 
of the files which are to be compared using a command string in the 
following formats 

dev s output=dev sinputl,dev sinput2/s 


wheres 

devs is any valid device specification. 

output is the filename and extension assigned to the output 

file. If no output file is indicated, output is 
directed to the terminal. 

inputl... are the input source filenames and extensions to be 
compared. 

/s is one of the switches listed in Table K-l. 


Source files are examined line by line for groups of lines which 
match. When a mismatch occurs, all differences are output until n 
successive lines in the first file are identical to n lines in the 
second file. The number (n) is a variable which the user can set with 
the /L switch. 
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K.1.1 Extensions 

No default extension is assigned by SRCCOM to the output file. The 
default extension for an input file is .MAC, representing a source 
file in MACRO language. 


K.1.2 Switches 

Command switches are generally placed at the end of the command string 
but may follow any filename in the string. The following switches 
can appear in the command string: 


Table K-l 
SRCCOM Switches 


Switch 

Meaning 

/B 

Compare blank lines. Without this switch, blank 
lines are ignored. 

/c 

Ignore comments (all text on a line preceded by a 
semicolon) and spacing (spaces and tabs). This 
switch does not cause a line consisting entirely 
of a comment to become a blank line, and therefore 
ignored in the line count. 

/F 

Include form feeds in the output file. (Form 

feeds are still compared if /F is not used, 

but they are not included in the output of 
differences.) 

/H 

Type list of switches available (help text). No 
I/O device is necessary since /H always prints the 
help text on the terminal. 

/L:n 

Specify the number of lines that determines a match 
(n is an octal number <*310). All differences 
occurring before and after a match are output. In 
addition, the first line of the current match is 
output after the differences to aid in locating 
the place within each file at which the 
differences occurred. The default value for n is 

3 . 

/s 

Ignore spaces and tabs. 


K.2 OUTPUT FORMAT 


The first line of each file is always output as identification and 
| also compared. A blank line is then printed, followed by 
differences between the files, in the following format 
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FI LEA 
A 

FILEB 
A 

********** 


1)1 

1) 

**** 

2)1 

2 ) 


% FILES ARE DIFFERENT 

The different lines are listed followed by a reference line which is 
the same for both files. Note the example below. 

The following example uses SRCCOM to compare an edited file and its 
backup version. The default value for a match is 3 lines. Blank 
lines are ignored but all other characters are compared. 

Following the example is a coded explanation of the comparison. 


.R SRCCOM 

*RK1 : LIN K 0. F6, LINK©. BAK 
a / 1)1 . TITLE 

\ 2)1 . TITLE 


RTLINK ROOT CODE X03-1 6 
RTLINK ROOT CODE X03-15 



1)1 

1) 

1) 

1) 

+• * * * 
2)1 
2 ) 

2) 

2) 


* * + * * J#c Jf- + * * 


B( 1)2 
C { 1) 


* * * * 


B{ 2)2 
C{ 2) 

He jf: )|c $ >fc He $ jf: H• 

B{ 1)2 RLSTRT : 

C { 1) RELF'TR: 

* * * * 

C( 2)2 RELPTR : 

He He He He He .+• He He He He 

B{ 1)2 MTITLE : 

C{ i) 

**** 

B{ 2)2 MTITLE : 

C{ 2) 

**#*#**#*111 


B 

C 

C 


( 


1)12 

1) 

1) 

1) 

He He He He 
2)12 

He He He He He He He He He He 


5 E V E N K = 314 5 2 ;MINIMUM CORE TO START LINKER 

. MCRLL . CSISPC, . CSIGEN, . SETTOP, . LOCK, . UNLOCK 
SEVENK» 31506 ; JUST BELOW 8K RESIDENT 


. MCRLL .CSISPC,. CSIGEN,. SETTOP,. LOCK,. UNLOCK 

. GLGBL RSWIT,RELPTR,FBTXT,OVLNUM,RELOVL,RLSTRT 
. GLOBL RELRDR,PNRELO,RELID1,RSIZ1,OVSIZi,OVLCDE 

. GLOBL RSWIT,RELPTR,FBTXT,OVLNUM,RELOVL 
. GLOBL RELRDR,PNRELO,RELID1,RSIZ1,OVSIZI,OVLCDE 

. BLKW ;CURRENT REL BLK OVERLRV NUM 

. BLKW ,POINTER TO CURRENT REL BLK LOCATION 

BLKW ,POINTER TO CURRENT REL BLK LOCATION 

.ASCII /R T-11 LINK X03-16/ 

.ASCII / LORD MRP / 

ASCII /R T-11 LINK X03-15/ 

.ASCII / LORD MRP / 

IF DF FB 

MOV OBLK,RLSTRT ,IND START OF OVL FOR REL BLK 

. END C 

BR 1$ 

BR 1$ 


XFILES ARE DIFFERENT 
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A Headers, consisting of the first line of each file? for 

identification purposes, 

B n)m. A notation where n is the number of the input file, and 

m is the page number (less than 256 decimal) of the input file 
on which the text appears. The right column lists the lines in 
the files which are different. 

C Following a section of differences, a line identical to each file 
is output for reference purposes* 

D Indicates that the files are different (this is printed on the 
system console , not in the output file)• 


This example uses the /Lsn switch and sets the number of lines that 
determines a match to 2 lines* The first two columns represent the 
input files: 


TEST FILE 1 
LINE C 
LINE E 
LINE C 
LINE D 
LINE F 
LINE H 
LINE I 
LINE J 


TEST FILE 2 
LINE C 
LINE D 
LINE C 
LINE E 
LINE F 
LINE 6 
LINE H 
LINE I 
LINE J 

The files are compared and differences listed on the line printer* 

*LP:=TEST1,TEST2/L:2 

m test file i 

2)1 TEST FILE 2 
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1)1 

LINE 

E 

1) 

LINE 

C 

1) 

LINE 

0 

1) 

LINE 

F 

1) 

LINE 

H 

**** 



2)1 

LINE 

D 

2) 

LINE 

C 

2) 

LINE 

E 

2) 

line 

F 

2) 

LINE 

G 

2) 

LINE 

H 


This message prints on the terminal indicating that the files are 
different. 

HFILES ARE DIFFERENT 


K.3 SRCCOM ERROR MESSAGES 

The following errors may be reported by SRCCOM: 


Messages 
?COR OVR? 

?IN ERR? 

?OUT ERR? 

?SWITCH ERROR? 

?TOO MUCH DIFFERENCE? 


Meaning 

Not enough memory to hold a particular 
difference section. 

A hardware error occurred in reading 
input. 

A hardware error occurred in writing 
output file, or output device full. 

An invalid switch was found or a switch 
other than /L was given a value. 

More than 310 (octal) lines of 
difference between two files were found. 
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PATCH 


The PATCH utility program is used to make code modifications to memory 
image (.SAV) files, including overlay-structured and monitor files. 
PATCH, like ODT, can be used to interrogate, and then to change, words 
or bytes in the file. 

PATCH provides eight relocation registers. Before changing a program 
with PATCH, copy the old file to a backup file with PIP, as the old 
file is modified when PATCH is used. 


L.l CALLING AND USING PATCH 
To run PATCH, type the command: 

R PATCH 

followed by the RETURN key in response to the dot printed by the 
monitor. PATCH prints a version number message: 

PATCH VO1-02 

and then prints the message: 

FILE NAME — 

* 

In response to the asterisk, enter the name of the file to be 
modified, using the following format: 

dev:filnam.ext/M/O 

where: 

3 ev: represents an optional device specification; if 

not specified, DK: is assumed. 

filnam.ext represents the name of the file which is to be 

patched, if an extension is not indicated, .SAV is 
assumed. 

must be used if the file is an RT—11 monitor file. 

/0 must be used if the file is an overlay-structured 

file. 
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After this information has been entered, the Command String 
nterpreter prints an asterisk indicating that it is ready to accept a 
command. Note that /0 and /M, if used, must be specified when P the 
file name is typed; they are not legal at any other time. 


L.2 PATCH COMMANDS 

Table L-l summarizes the PATCH commands. 


I 


Table L-l 

PATCH Commands 

Command 

Action 

Vr;nR 

Set relocation register n to value Vr. 

b;B 

Set bottom address of overlay file to b. 

[s:]r,o/ 

Open word location Vr + o in overlay 
segment s. 

[s:]r,o\ 

Open byte location Vr + o in overlay 
segment s. 

<CR> 

Close currently open word/byte. 

<LF> 

Close currently open word/byte and open 
the next one. 

A 

t or 

Close currently open word/byte and open 
the previous one. 

@ 

Close the currently open word and open 
the word addressed by it. 

F 

Begin patching a new file. 

E 

Exit to RT-ll monitor. 


Explanations of each command follow, 
commands is provided in Section L.3. 


An example of the use of the 


I>.2.1 Patch a New File 

The F command causes PATCH to close 
a new file name to be patched. 


the file being patched. 


and accept 
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L.2.2 Exit from PATCH 

The E command causes PATCH to close the file being patched and return 
control to the RT-11 monitor. 

L.2.3 Examine, Change Locations in the File 

For a non-overlay file, a word address may be opened, as with ODT, by 
typing: 

[<relocation register>,]offset/ 

At this point, PATCH will type out the contents of the location and 
wait for the user to type in either new location contents (in octal) 
or another command. 

In an overlay file, the format is: 

[<segment nuraber>:][<relocation register>,]offset/ 

Where <segment number> is the overlay segment number as it is printed 
on the link map for the file. If it is omitted, the root segment is 
assumed. 

Similarly, to open a byte address in file, the format is: 

[<relocation register>,]offset\ 
for non-overlay files, or 

(<segment number>:][{relocation register>,]offset\ 
for overlay files. 

Once a location has been opened, the user may optionally type in the 
new contents in the format: 

[{relocation register>,lvalue 

followed by one of these control characters: 


{carriage return> 


Close the current location by changing 
its contents to the new contents (if 
specified), and await more control 
input. 


{line feed> 


Close the current location, and open the 
next word/byte. 


t or ~ 


Close the current location, and open the 
previous word/byte. 


0 


Close the current word location, and 
open the word addressed by it (in the 
same segment if an overlay file)• 
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L.2.4 Set Bottom Address 

To patch an overlay file, PATCH must know the bottom address at which 
the program was linked if it is different from the initial stack 
pointer. This is the case if the program sets location 42 in an 
.ASECT. To set the bottom address, type: 

<bottom address>;B 

Note that the B command must be issued before any locations are opened 
for modification. 


L.2.5 Set Relocation Registers 

The relocation registers 0-7 are set, as with ODT, by the R command. 
The R command has the format: 

Relocation value>; Relocation register>R 

Once one of the eight relocation registers has been set, the 
expression: 

<relocation register>,<octal number> 
typed as part of a command will have the value: 

<relocation value> + <octal number> 


L. 3 EXAMPLES USING PATCH 

The following example shows how to patch a non-overlaid file. Assume 
the following program (EXAM): 

.MAIN, RT*ii MACRO VM02-08 PACE 1 


1 

2 


3 

000015 

CRt 

13 

4 

08001 4 

LFt 

12 

5 

0000001 

•C8ECT 

MAIN 

8 


• MC ALL 

.PRINT,.EXIT 

7 


«NIIST 

BEX 

8 080000 

124 MSCI 

.ASCII 

/THIS IS A SUCCESSFUL PaTCM/«CR><LF> 

9 


.LIST 

BEX 

10 00034 

000403 STAHTI 

BR 

EXIT 

11 00036 


.PRINT 

«M8G 

12 00044 

EXiTI 

.EXIT 


13 

008034' 

.END 

START 

This program has been assembled 

with MACRO ana linked with LINK; 


execution causes no output of text: 


.R EXfiM 
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To make a line of text print on the terminal , PATCH is used as 
follows: 

R PATCH 
PATCH V01-02 

FILE NAME-- 

♦ EXAM. SAV 
♦1000;0R 

♦ 0 1 34 / 402 240 

*E 

Now when the program is executed: 

R EXAM 

THIS IS A SUCCESSFUL PATCH 

The next example demonstrates a similar situation, only includes an 
overlay file. These programs have been assembled and linked? the 
output of both operations is included: 


.MAIN, 

KT•1i MACRO VM02»08 3 

-SEP-74 PAGE 1 

1 

2 

3 


008019 

CRP 

IS 

4 


000012 

LM 

12 

9 


000087 

PC* 

X7 

6 


008080' 

•CSECT 

MAIN 

7 



.GL06L 

ENTRY,MSSl 

8 



•MCALL 

.PRINT,.EXIT 

9 



• NUST 

BEX 

10 

00000 

124 MS to | 

•ASCIZ 

/THIS IS A SUCCESSFUL PATCH/ 

11 

0004 a 

124 MSS 11 

•ASCIZ 

/this is an overlay patch/ 

12 



• LIST 

BEX 

13 

00066 

000403 START! 

bH 

EXIT 

14 

00070 


•PRINT 

«M3G 

IS 

00076 

004767 EXIT! 
000000G 

4SR 

PCiENTRY 

16 

00102 


• EXIT 


17 


000066' 

» END 

START 
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.MAIN, RT-11 MACRO VM02-08 3-SEP-74 PAGE 1 

1 

2 


3 


000015 

CR« 

15 

4 


000012 

LM 

12 

9 


000007 

PC* 

X7 

6 


000000' 

• CSECT 

QVL 

7 



•MCALL 

.PRINT 

6 



•GLQ0L 

MSG 1 

9 



•GLQUl 

ENTRY 

10 

00000 

000403 ENTRYI 

BR 

RETURN 

11 

00002 


.PRINT 

«MSG1 

12 

00010 

000207 RETURNI 

RTS 

PC 

IS 


000001• 

.END 



RT-li LINK 

PTCH .SAV 

X03-10 

LOAD MAP 

03-SEP-74 




SECTION ADUR 

SUE 

ENTRY ADOR ENTRY 

ADOR 

entry 

ADOR 

, ABS. 000000 
MAIN 001122 

001122 

000104 

MSG 1 001157 




overlay region 
OVL 0012S0 

000001 

000012 

SEGMENT 000001 

ENTRY 001200 





TRANSFER ADDRESS * 00 1 2 10 
HIGH LIMIT ■ 001242 


Running the program (PTCH) produces no terminal output: 

. R PTCH 


But by using PATCH to modify the file as follows: 
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.R PATCH 

PATCH V01-@2 

FILE NAME-- 
*PTCH. SAV/O 
*1230,0R 

*1:0,0/ 403 240 

*E 


the following line results: 

. R PTCH 

THIS IS AN OVERLAV PATCH 


L.4 PATCH ERROR MESSAGES 

Error messages which may occur under PATCH follow. 


Message 

7ADDR NOT IN SEG7 

7BAD SWITCH? 

7BOTTOM ADDR WRONG? 

7INCORRECT FILE SPEC? 

7INSUFFICIENT CORE? 


?INVALID RELOC REG? 

7INVALID SEG NO? 
7MUST OPEN WORD? 

7MUST SPECIFY SEG? 


Meaning 


The address is not in the specified 
overlay segment. 

Typed a switch other than /O or /M. 

The bottom address specifed or contained 
in location 42 of an overlay file is 
incorrect. Specify the correct one 
using the b:B command. 

The response to the "FILE NAME —" 
message was not of the correct form. 
Try again. 

PATCH did not have enough memory to hold 
the file*8 device handler plus the 
internal "segment table." This message 
should not occur. 

Tried to reference a relocation register 
outside the range 0-7. 

The segment number S: does not exist. 

The @ command was typed when a byte 
location was open. 

The address referenced is not in the 
root section; a segment number S: must 
be used. 


L-7 


January 1976 









PATCH 


?N0 ADDR OPEN? 

The Cline feed>, t or @ command was 
typed when no location was open. 

?NOT IN PROGR BOUNDS? 

Tried to open a location beyond the end 
of the file. 

?ODD ADDRESS? 

Tried to open a word address which was 
odd. (Use "\".) 

?ODD BOTTOM ADDR? 

The bottom address specified or 
contained in location 42 of an overlay 
file is odd. 

?PROG HAS NO SEGS? 

The file specified as an overlay file is 
not. 

7READ ERROR? 

File I/O error in reading. 

?WRITE ERROR? 

File I/O error in writing. 
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PATCHO 


The RT-11 PATCHO program is used to correct and update object modules 
(files output by the assemblers or by the FORTRAN compiler). It is 
particularly useful when making corrections to routines. that are in 
.OBJ format for which the source files are not available. PATCHO 
cannot be used to patch libraries built by LIBR, but it can be used to 
patch the OBJ modules from which a library is built. 


M.l CALLING AND USING PATCHO 
To run PATCHO type the command: 

R PATCHO 

in response to the dot printed by the Keyboard Monitor. When PATCHO 
is ready to accept commands, an asterisk is printed. The standard 
RT-11 command string is not used for PATCHO. Specific commands 
(described in Section M.2) are typed in response to the asterisk. 

Type CTRL C to halt PATCHO at any time and return control to the 
monitor. To restart PATCHO, type R PATCHO or the REENTER command in 
response to the monitor's dot. 


M.2 PATCHO COMMANDS 

There are nine commands and arguments accepted by PATCHO. All 
arguments to a command must be separated from the command name by one 
or more spaces (e.g., POINT TOP is acceptable, POINTTOP is not). 
Commands are terminated by a carriage return. 


M.2.1 OPEN Command 

The OPEN command sets input and output file names. When the command 
is given, PATCHO prints: 

ENTER INPUT FILE* 
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on the console terminal, and waits for a standard RT-11 device and 
flle .-f pec f f ^ cat ^ 01 ? to be entered (devsfilnam.ext) . After the input 
specification is given, followed by a carriage return, PATCHO responds 
with: 


ENTER OUTPUT FILE* 

^ de Y ic ? anc * specification (followed by a carriage return) for 

the desired output file is now accepted from the console. 


NOTE 

There is no default extension. 
Therefore, the user must explicitly 
specify the filename and extension. 


Example: 


♦OPEN 

E N T E R IN P U T FIL E * R K1 1 0 T S ♦ 0 B J 
E N T E R 0 U T P U T FIL E * R K1 1 N E W 0 T S ♦ 0 B J 


M.2.2 POINT Command 

The POINT command locates an object module of a given name (used with 
nvm^ atena ^ d r. ob 3 ect modules) and prepares it for subsequent WORD. 
B YT E, or DUMP operations. POINT takes one argument—the module name 
to be located. 


Example: 


*POINT OTINIT 


M.2.3 WORD Command 

The WORD command modifies a given word in an object module. There may 

t>vmc» eVeral ar ? uments to the command , entered as illustrated below (the 
BYTE command is also included since its arguments are exactly the 
same; refer to Section M.2.4): y 


Address Specifier 


f WORD 
\ BYTE J 


Value Specifier 


CSECT + OFFSET = C #'|NAME OF 
NAME / % >CSECT OR 

L J GLOBAL SYMBOL 1 


Sr) 


OFFSET 


where in the Address Specifier: 


1 * the name of the CSECT which contains the word to be 

modified. The CSECT must be present in the current module 
(the one specified in the POINT command). 
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The CSECT NAME is optional; if omitted, the blank CSECT 

is assumed. To represent a CSECT name which contains 
embedded blanks (. ABS.), a backarrow (SHIFT 0) or underscore 
character should be used in place of each embedded blank. 

2. OFFSET is the octal location within the CSECT that is to be 
modified. OFFSET must be present. 

3. & is a delimiter and must be present. 

In the Value Specifiers 

1. If # is used, the absolute value of the OFFSET in the Value 

Specifier field is placed in the target location (the address 
indicated by the Address Specifier). 

For example: 

♦WORD PR0G+24=#4 

This command patches location 24 in CSECT PROG to contain the 
value 4. 

2. If % is used, displaced relocation is generated on the Value 
Specifier. This mode is used for PC-relative references. 
For examples 

♦ W 0 R D P R 0 G+2 4=% P R' 0 61+2 4 

This command patches PROG+24 to contain the values 

Address (PROG1+24)-Address (PROG+26) 

3. ’ If neither # or % are specified, the address of the Value 

Specifier is placed in the target location. For examples 

♦WORD PR0G+24=PR0G+14 

This causes the word at PROG+24 to contain the address of the 
word at PROG+14, whiles 

♦WORD PR0G+24=SYMB0L+0 

causes the word at PROG+24 to contain the address of the 
global symbol "SYMBOL". 

4. GLOBAL is optional and is the name of a global symbol whose 
value (address) is to be used in the word to be modified. 

5. The characters + or - are optional and indicate the sian of 

the following OFFSET. If a global symbol is indicated, a + 

(or -) and OFFSET must be present. 


M.2.4 BYTE Command 

The BYTE command modifies a given byte in an object module. The 
arguments are the same as for WORD, explained in Section M.2.3. 
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Example: 


♦BYTE CSECTA+21=#101 

The byte in CSECTA whose offset is 21 is patched to contain octal 101 
(ASCII "A"). 


M.2.5 DUMP Command 

The DUMP command prints the contents of the object module currently 
being pointed to and causes an automatic POINT to the next module in 
the input file, if any. Use the monitor SET LP CR command first for 
correct output format. 


NOTE 

LIST and DUMP go to LP: (lineprinter) 

by default. If the user wants LIST and 
DUMP to go to the terminal, he must 
execute an ASSIGN TT:6 command before 
typing R PATCHO. 

Refer to Section M.4 for an example of the DUMP command. 


M.2.6 LIST Command 

The LIST command lists the names of all the object modules in the 
input file in the order in which they appear in the file. A POINT 
command should be given after the LIST command to assure that 
PATCHO is positioned at the desired module for the next operation. 
LIST lists the names of all object modules in a file without chanqinq 
the module being pointed to. 

Refer to Section M.4 for an example of the LIST command. 


M.2.7 EXIT Command 

The EXIT command returns to the operating system terminating a patch 
session and closing a file. The EXIT command takes no argument. As 
the EXIT command is executed, ENTER CHECKSUM:- - - is displayed. The 

user should type a six-digit octal number corresponding to the 
appropriate checksum for the patch (if any). If the checksum agrees, 
PATCHO prints STOP— and returns control to the monitor. If the 
checksum does not agree, PATCHO prints PAUSE — ?BAD PATCH? and waits 
for user input. The user has two options: typing a CTRL C at this 
point aborts PATCHO without closing the output file, thus allowing 
PATCHO to be rerun and the patch to be reentered. For example: 


*EXIT 

ENTER CHECKSUM; 115570 

PAUSE -- ?BRD PATCH? 

~C 
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Typing a carriage return causes the output file to be closed, despite 
the bad patch, and returns control to the monitor. Note that in the 
latter case, if the output and input files were called by the same 
name and extension, the input file is destroyed and the output file 
contains an incorrect patch. 


* 



M.2.8 DEC Command 

The DEC command is used generally by maintainers when creating system 
patches and when the proper checksum for the patch being made is | 
unknown. If a DEC command is issued during a patch session, the EXIT 
command is automatically modified to display: 

ENTER CHECKSUM: 

followed by the correct checksum for the patch just completed. The 
checksum computed by PATCHO is derived from all of the commands 
entered during the session, thereby providing a safeguard against 
typographical errors. If the DEC command is used, it is the first 
command given. 

*DEC 


* E XIT 

ENTER CHECKSUM: 115578 
STOP — 



M.2.9 HELP Command 

The HELP command prints an explanation of PATCHO commands. The HELP 
command takes no arguments. 




M. 3 PATCHO LIMITATIONS 

Note the following limitations on the use of PATCHOs 

1. PATCHO only works with object modules or concatenated object 
modules, not with libraries. 

2. PATCHO always copies its input file to its output file as it 
makes changes. 

3. As a consequence of 2 (above) the POINT command can only be 
used to point to modules that physically follow the current 
module in the input file. 

4. If changes are being made to a file, PATCHO must be given an 
EXIT command when all the changes are complete in order to 
assure that the entire input is copied to the output (i.e., 
CTRL C should not be used). 

5. The LIST and DUMP commands will work in an 8K system only 
if an ASSIGN TT:6 command has been entered prior to running 
PATCHO. Otherwise 12K is required for these two commands. 
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M.4 EXAMPLES 


The following is an example of the PATCHO command LIST in which a few 
of the names of object modules in the library file (OTS.OBJ) are 
listed: 


I S I- 


OBJECT modules I 

f RRS3 

XVEC 

IVECP 

IPVEC 

me 

me? 

PPVEC 

ovec 

OVECP 

OPVEC 

lvec 

LV6CP 

LPVEC 

ERRS 

AOTS 

OTINIT 

The next example is a sample of output produced by the PATCHO 
Command. The module is dumped by formatted binary block. 

*DUMP 


DUMP 


DUMP OF MODULE LPS0 


BLOCK TYPE G3D 


global 

USAGE 

DEFINED 

RELOC 

EXTERNAL 

SIZE/ADRS 

LPS0 

MOD NAME 

NO 

NO 

no 

0 

. abs. 

CSECT 

YES 

NO 

NO 

0 

errarg 

GLOBAL 

NO 

NO 

YES 

0 

ERRPDL 

GLOBAL 

NO 

NO 

YES 

0 

ERRSYN 

GLOBAL 

NO 

NO 

YES 

0 

BLOCK TYPE GSD 

global USAGE 

DEFINED 

RELOC 

EXTERNAL 

SIZE/ADRS 

EVAL 

• 

a 

global 

NO 

NO 

YES 

0 

• 

BLOCK TYPE GSD 

global USAGE 

defined 

RELOC 

external 

SIZE/ADRS 

USE 

global 

YES 

YES 

YES 

104 

. abs. 

TRAN ADR 

YES 

NO 

NO 

1 


BLOCK TYPE GSD END 


BLOCK TYPE RLD 

ADDRESS RLD TYPE GLOBAL OFFSET 
1772 LCTR DEF 0 
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BLOCK TYPE TXT 
ADDRESS CONTENTS 


0 

0 

0 

0 

2 

0 

0 

0 

4 

0 

0 

0 

6 

0 

0 

0 

10 

0 

0 

0 

12 

P 

0 

0 

0 

• 

• 

1476 

12602 

202 

25 

1500 

12600 

200 

25 

1502 

207 

207 

0 


BLOCK TYPE MOD END 


M.5 PATCHO ERROR MESSAGES 
Message 
?BAD CHECKSUM? 

?BAD OBJ? 

?DUMP ERROR? 

?ILLEGAL COMMAND? 

7MODULE NOT FOUND? 


?MORE THAN 15 CHANGES? 


Explanation 

A formatted binary block in the input 
file has a checksum which does not agree 
with that calculated for its contents. 

The input file contains information 
which cannot be interpreted as an object 
module. 

An input/output error occurred while 
dumping a module. 

A command line was not recognized, or it 
was not in the proper format for the 

particular operation. | 

• 

The module requested in a POINT command 
was not found in the input file between 
the position of the file at the time of 

the POINT and the file's end. | 

Too many changes have been specified for 
a particular module. The patch should 
be broken up into several steps. 


?MORE THAN 5 CSECTS REQUIRE CHANGE? 

An attempt has been made to patch 
locations in too many different CSECTS. 
The patch should be made in several 
steps• 


?NO FILE OPEN? 


70FFSET? 


An attempt was made to use a command 
other than "DEC" or "HELP" before an 
OPEN command was issued. 

The offset supplied in a WORD or BYTE 
command is not an octal number , or is in 
improper format. 
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Message 


Explanation 

70UTPUT ERROR? 

A hardware 
write-lock 

error (or possibly a 

condition) occurred while 


attempting to write the output file. 

?OUTPUT FILE TOO SMALL? The space allocated to the output file 

is too small. This may be corrected by 
compressing the device with PIP (if 
enough total space is free on the 
device ), or by using another device for 
output. 

PAUSE ?BAD PATCH? The checksum entered on exit does not 

agree with that calculated by PATCHO. 


M.5.1 Run-Time Error Messages 

Because PATCHO is a FORTRAN program, run-time error messages may occur. 
!E?_? i ,!} d _ a _ complete explanation of each run-time error refer to the RT-11/ 
RSTS/E FORTRAN IV User 1 s Guide or the RT-11 System Message Manual . 

Listed below are four of the most important run-time error messages which 
may be encountered. 


23 


28 


29 


30 


FATAL HARDWARE I/O ERROR 

A hardware error has been detected during an I/O 
operation. 

FATAL OPEN FAILED FOR FILE 

A file could not be found, there was no room in 
the device, or FORTRAN selected a channel already 
in use. 

FATAL NO ROOM FOR DEVICE HANDLER 

There is not enough free memory left to 
accommodate a specific device handler. 

FATAL NO ROOM FOR BUFFERS 

There is not enough free memory left to set ud 
required I/O buffers. v 
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DISPLAY FILE HANDLER 


This appendix describes the assembly language graphics support 
provided under RT-11 for the GT40, GT44, and DECLab-11 display 

hardware systems. 

The following manuals are suggested for additional reference: 

For GT40 users: 

1. GT40 User's Guide (DEC-ll-HGTGA-A-D) 

For GT44 users: 

1. GT44 User's Guide (DEC-11-HGT44-A-D) 

For DECLab-11 users: 

1. VT11 Graphics Display Processor Manual (DEC-ll-HVGTA-A-D) 

2. RT-11 BASIC Reference Manual (DEC-11-LBACA-B-D) 


N.l DESCRIPTION 

The GT40, GT44, and DECLab-11 have hardware configurations that 
include a display processor and CRT (cathode ray tube) display. The 
GT44 has a 17-inch tube; the GT40 and DECLab-11 use a 12-inch tube. 
Both systems are equipped with light pens and hardware character and 
vector generators, and are capable of high-quality graphics. The 
Display File Handler supports this graphics hardware at the assembly 
language level under the RT-11 monitor. 


N.1.1 Assembly Language Display Support 

The Display File Handler is not an RT-11 device handler, since it does 
not use the I/O structure of the RT-11 monitor. For example, it is 
not possible to use PIP to transfer a text file to the display via the 
Display File Handler. Rather, the Display File Handler provides the 
graphics programmer the means for the display of graphics files and 
the easy management of the display processor. Included in its 
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capabilities are such services as interrupt handling, light pen 
support, tracking object, and starting and stopping of the display 
processor. 

The Display File Handler manages the display processor by means of a 
base segment (called VTBASE) which contains interrupt handlers, an 
internal display file and some pointers and flags. The display 
processor cycles through the internal display file; any user graphics 
files to be displayed are accessed via display subroutine calls from 
the Handler's display file. In this way, the Display File Handler 
exerts control over the display processor, relieving the assembly 
language user of the task. 

Through the Display File Handler, the programmer can insert and remove 
calls to display files from the Handler's internal display file. Up 
to two user files may be inserted at one time, and that number may be 
increased by re-assembling the Handler. Any user file inserted for 
display may be blanked (the subroutine call to it bypassed) and 
unblanked by macro calls to the Display File Handler. 

Since the Handler treats all user display files as graphics 
subroutines to its internal display file, a display processor 
subroutine call is required. This is implemented with software, using 
the display stop instruction, and is available for user programs. 
This instruction and several other extended instructions implemented 
with the display stop instruction are described in Section N.3. 

The facilities of the Display File Handler are accessed through a 
library of macros (VTMAC) which generate calls to a set of subroutines 
in VTLIB. VTMAC is the MACRO library, and its call protocol is 
similar to that of the RT-11 macros. The expansion of the macros is 
shown in Section N.6. VTMAC also contains, for convenience in 
programming, the set of recommended display processor instruction 
mnemonics and their values. The mnemonics are listed in Section N.7 
and are used in the examples throughout this appendix. 

VTCALl through VTCAL4 are the set of subroutines which service the 
VTMAC calls. They include functions for display file and display 
processor management. These are described in detail in Section N.2. 
VTCALl through VTCAL4 sure currently constructed, along with the base 
segment VTBASE, as a library of (five) modules, called VTLIB. 


N.1.2 Monitor Display Support 

The RT-11 monitor, under Version 2, directly supports the display as 
console device. A keyboard monitor command, GT ON (GT OFF) described 
in Section 2.7.1, permits the selection of the display as console 
device. Selection results in the allocation of approximately 1.25K 
words of memory for text buffer and code. The buffer holds 
approximately 2000 characters. 

The text display includes a blinking cursor to indicate the position 
in the text where a character is added. The cursor initially appears 
at the top left corner of the text area. As .lines are added to the 
text the cursor moves down the screen. When the maximum number of 
lines are on the screen, the top line is deleted from the text buffer 
when the line feed terminating a new line is received. This causes 
the appearance of "scrolling", as the text disappears off the top of 
the display. 
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When the maximum number of characters have been inserted in the text 
buffer, the scroller logic deletes a line from the top of the screen 

Xc?S?/°^/°^ ad ? iti0 2 a L characte «- Text may appear to move 
(scroll) off the top of the screen while the cursor is in the middle 
or a line. 


The Display File Handler can operate simultaneously with the scroller 
program permitting graphic displays and monitor dialogue s ap^ar “ 
the screen at the same time. It does this by inserting its internal 

display file into the display processor loop through the text buffer 
However, the following should be noted. Under the Single-Job Monitor, 
if a program using the display for graphics is running with the 
scroller in use (that is, GT ON is in effect), and the program does a 
soft exit (.EXIT with RO not equal to 0) with the display stopped, 
the display remains stopped until a CTRL C is typed at the keyboard 


This can be recognized by failure of the monitor to echo on the screen 
when expected. If the scroller text display disappears after a pro- 
gram exit, always type CTRL C to restore. If CTRL C fails to restore 
the display, the running program probably has an error. 

Four scroller control characters provide the user with the capability 
of halting the scroller, advancing the scrolling in page sections, 
and printing hard copy from the scroller. These are described in 
Chapter 2. 


NOTE 

The scroller logic does not limit the 
length of a line, but the length of text 
lines affects the number of lines which 
may be displayed, since the text buffer 
is finite. As text lines become longer, 
the scroller logic may delete extra 
lines to make room for new text, 
temporarily decreasing the number of 
lines displayed. 


N.2 DESCRIPTION OF GRAPHICS MACROS 

The facilities of the Display File Handler are accessed through a set 
of macros, contained in VTMAC, which generate assembly language calls 
to the Handler at assembly time. The calls take the form of 
subroutine calls to the subroutines in VTLIB. Arguments are passed to 
the subroutines through register 0 and, in the case of the .TRACK 
call, through both register 0 and the stack. 

This call convention is similar to Version 1 RT-11 I/O macro calls, 
except that the subroutine call instruction is used instead of the EMT 
instruction. If a macro requires an argument but none is specified, 
it is assumed that the address of the argument has already been placed 
in register 0. The programmer should not assume that RO is preserved 
through the call. 


N. 2.1 .BLANK 

The .BLANK request temporarily blanks the user display file specified 
in the request. It does this by by-passing the call to the user 
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.1 la „ file which prevents the display processor from cycling 
2SSS tie usef file, P effectively blanking it. This effect can later 
be cancelled by the .RESTR request, which restores the user fil ®* 
Shen Se call returns, the user is assured the display processor is 
not in the file that was blanked. 


Macro Call: .BLANK .faddr 

where: .faddr is the address of the user 

display file to be blanked. 


Errors: 


No error is returned. If the file specified was not 
Handler file or has already been blanked, the request 


found in 
is ignored. 


the 


N.2.2 .CLEAR 

The .CLEAR request initializes the Display File Handler, clearing out 
any calls to user display files and resetting all of the internal 
flags and pointers. 

After initialization with .LNKRT (Section N.2.4), the .CLEAR request 
can be used any time in a program to clear the display and to reset 
pointers. All calls to user files are deleted and all pointers to 
status buffers are reset. They must be re-inserted if they are to be 
used again• 


Macro Call: •CLEAR 
Errors: 


None. 

Example: 

This example uses a .CLEAR request to initialize the Handler, then 
later uses the .CLEAR to re-initialize the display. The first .CLEAR 
is used for the case when a program may be restarted after a CTRL C or 
other exit. 



HR 

RSTRT 

EX1I 

sis 

#20000, PM* 

RSTRTl 

.UNLNK 

.LNKRT 

.CLEAR 



.INSRT 

•FILEl 

1SI 

.TTYIN 



CMPB 

#12,R0 


sne 

.CLEAR 

IS 


.INSRT 

#FILE2 

• 

FILE1I 

POINT 

0 

500 

LONGV 

• 


50011 NT/ 

0 

DRET 

0 


|SET RENTER BIT IN J3W 
I clears LINK flag for restart 
I SET UP VECTORS, START DISPLAY 
UNITIALIZE handler. 

I DI SPLAY A PICTURE 
I WAIT FOR * KEY STRIKE 
I LINE FEED? 

I NO,LOOP 

IYES, CLEAR DISPLAY 
IDISPLAY NEW PICTURE 


f AT POINT ((a, 500) 


I DR* W A LINE 
I TO (500,500) 
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FIU2I POINT 


I AT POINT (500,0) 


500 

0 

LONG V 

01INTX 

500 

ORET 

0 


I ORAN A LINE 
I TO (500*500) 


END ext 


N.2.3 .INSRT 

The .INSRT request inserts a call to the user display file specified 
in the request into the Display File Handler's internal display file. 
.INSRT causes the display processor to cycle through the user file as 
a subroutine to the internal file. The handler permits two user files 
at one time. The call inserted in the handler looks like the 
following: 


DISPLAY SUBROUTINE 
RETURN ADDRESS 
SUBROUTINE ADDRESS 


DJSR 

.+4 

.faddr 


The call to the user file is removed by replacing its address with the 
address of a null display file. The user file is blanked by replacing 
the DJSR with a DJMP instruction, bypassing the user file. 

Macro Call: .INSRT .faddr 


where: .faddr is the address of the user 

display file to be inserted. 


Errors: 


The .INSRT request returns with the C bit set if there was an error in 
processing the request. An error occurs only when the Handler's 
display file is full and cannot accept another file. If the user file 
specified exists, the request is not processed. Two display files 
with the same starting address cannot be inserted. 

Example: 

See the examples in Sections N.2.2 and N.2.4. 


N.2.4 .LNKRT 

The .LNKRT request sets up the display interrupt vectors and possibly 
links the Display File Handler to the scroll text buffer in the RT-11 
monitor. It must be the first call to the Handler, and is used 
whether or not the RT-11 monitor is using the display for console 
output (i.e., the KMON command GT ON has been entered). 

The .LNKRT request used with the Version 2 RT-11 monitor enables a 
display application program to determine the environment in which it 
is operating. Error codes are provided for the situations where there 
is no display hardware present on the system or the display hardware 
is already being used by another task (e.g., a foreground job in the 
Foreground/Background version). 


N-5 






Display File Handler 


The existence of the monitor scroller and the size of the Handler's 
subpicture stack are also returned to the caller. If a previous call 
to .LNKRT was made without a subsequent .UNLNK, the .LNKRT call is 
ignored and an error code is returned. 

Macro Call* .LNKRT 

Errors: 

Error codes are returned in RO, with the N condition bit set. 


Code 

Meaning 

-1 

No VT11 display hardware is 
present on this system. 

-2 

VT11 hardware is presently 
in use. 

-3 

Handler has already been 
linked. 


On completion of a successful .LNKRT request, RO will contain the 
display subroutine stack size, indicating the depth to which display 
subroutines may be nested. The N bit will be zero. 

If the RT-11 monitor scroll text buffer was not in memory at the time 
of the .LNKRT, the C bit will be returned set. The KMON commands 
GT ON and GT OFF cannot be issued while a task is using the display. 

Example: 


START' 

.LNKRT 



SMI 

ERROR 


BCS 

CONT 


.SCROL 

• SBOF 

CONTI 

. INSRT 

•FILE1 

1SI 

.TTYIN 



CMPB 

•12,R0 


8NE 

.UNLNK 

.EXIT 

IS 

38UFI 

.BYTE 

5 


.BYTE 

7 


.WORD 

1000 

FILE 11 

POINT 

500 

500 

ChAR 



.ASCII 

.EVEN 

DRET 

0 

/THIS IS FILE 


ERROR' Error routine 


'LINK TO MONITOR 
'ERROR DOING LINK 
I NO SCROLL IF C SET 
IA0JUST SCROLL PARAMETERS 
'DISPLAY A PICTURE 
'WAIT FOR KEY STRIKE 
'LINE FEED? 

'NO, LOOP 

'YES, UNLINK AND EXIT 


'LINE COUNT OF 5 
'INTENSITY 7(SCALE OF 1-8) 
'POSITION OF TOP LINE 

'AT POINT (500,500) 


'DISPLAY SOME TEXT 
l, TYPE CR TO EXIT/ 
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N.2.5 .LPEN 

The .LPEN request transfers the address of a light pen status data 
buffer to VTBASE. Once the buffer pointer has been passed to the 
Handler, the light pen interrupt handler in VTBASE will transfer 
display processor status data to the buffer, depending on the state of 
the buffer flag. 

The buffer must have seven contiguous words of storage. The first 
word is the buffer flag, and it is initially cleared (set to zero) by 
the .LPEN request. When a light pen interrupt occurs, the interrupt 
handler transfers status data to the buffer and then sets the buffer 
flag non-zero. The program can loop on the buffer flag when waiting 
for a light pen hit (although doing this will tie up the processor, 
and in a Foreground/Background environment, timed waits would be more 
desirable). No further data transfers take place, despite the 
occurrence of numerous light pen interrupts, until the buffer flag is 
again cleared to zero. This permits the program to process the data 
before it is destroyed by another interrupt. 

The buffer structure looks like this: 

Buffer Flag 
Name 

Subpicture Tag 

Display Program Counter (DPC) 

Display Status Register (DSR) 

X Status Register (XSR) 

Y Status Register (YSR) 

The Name value is the contents of the software Name Register 
(described in N.3.5) at the time of interrupt. The Tag value is the 
tag of the subpicture being displayed at the time of interrupt. The 
last four data items are the contents of the display processor status 
registers at the time of interrupt. They are described in detail in 
Table N-l. 

Macro Call: .LPEN .baddr 

where: .baddr is the address of the 7-word 

light pen status data buffer. 


Errors: 


None. 


If a .LPEN was already issued and a buffer specified, the new buffer 
address replaces the previous buffer address. Only one light pen 
buffer can be in use at a time. 


Example: 

LOOP I 


,JNSRT #LFILE 
.LPEN PLBUF 
TST LBUF 

«E0 LOOP 


IDISPLAY LPILE 
I SET UP LPEN BUFFER 
ITEST LBUF FLAG, WHICH 
(WILL BE BET N0N*ZER0 

fON light pen hit. 


» PROCESS OAT* IN LBUF HERE 
CLR LBUF 

BR LOOP 


I clear the buffer flag, 

^PERMITTING ANOTHER "HIT" 
FGO WAIT FOR IT, 
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18UFI •BLKW 7 |SEVEN t*ORO LPEN BUFFER 

LFILEl 


Table N-l 

Description of Display Status Words 


Bits 

Significance 

DISPLAY PROGRAM COUNTER (DPC=172000) 

0-15 

Address of display processor 
program counter at time of 
interrupt. 

DISPLAY STATUS REG! 

CSTER (DSR=172002) 

0-1 

Line Type 

2 

Spare 

3 

Blink 

4 

Italics 

5 

Edge Indicator 

6 

Shift Out 

7 

Light Pen Flag 

8-10 

Intensity 

11-14 

Mode 

15 

Stop Flag 

X STATUS REGISTER 

:XSR=172004) 

0-9 

X Position 

10-15 

Graphplot Increment 

Y STATUS REGISTER ( 

YSR=172006) 

0-9 

Y Position 

10-15 

Character Register 
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N.2.6 .NAME 

The .NAME request has been added to the Version 2 Handler. The 
contents of the name register are now stacked when a subpicture call 
is made. When a light pen interrupt occurs, the contents of the name 

register stack may be recovered if the user program has supplied the 

address of a buffer through the .NAME request. 

The buffer must have a size equal to the stack depth (default is 10) 

plus one word for the flag. When the .NAME request is entered, the 

address of the buffer is passed to the Handler and the first word (the 
flag word) is cleared. When a light pen hit occurs, the stack's 
contents are transferred and the flag is set non-zero. 

Macro Call: .NAME .baddr 

where: .baddr is the address of the name register 

buffer. 

Errors: 

None. 

If a .NAME request has been previously issued, the new buffer address 
replaces the previous buffer address. 


N.2.7 .REMOV 

The .REMOV request removes the call to a user display file previously 
inserted in the handler's display file by the .INSRT request. All 
reference to the user file is removed, unlike the .BLANK request, 
which merely bypasses the call while leaving it intact. 

Macro Call: .REMOV .faddr 

where: .faddr is the address of the display file to be 

removed. 

Errors: 

No errors are returned. If the file address given cannot be found, 
the request is ignored. 


N.2.8 .RESTR 

The .RESTR request restores to view a user display file that was 
previously blanked by a .BLANK request. It removes the by-pass of the 
call to the user file, so that the display processor once again cycles 
through the user file. 

Macro Call: .RESTR .faddr 

where: .faddr is the address of the user file that is 

to be restored to view. 

Errors: 

No errors are returned. If the file specified cannot be found, the 
request is ignored. 
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N.2.9 .SCROL 

This request is used to modify the appearance of the Display Monitor*s 
text display* The .SCROL request permits the programmer to change the 
maximum line count, intensity and the position of the top line of text 
of the scroller. The request passes the address of a two-word buffer 
which contains the parameter specifications. The first byte is the 
line count, the second byte is the intensity, and the second word is 
the Y position. Both line count and Y position must be octal numbers. 
The intensity may be a number from 1 to 8, ranging from lowest to 
highest intensity. If an intensity of 1 is specified, the scroller 
text will be almost unnoticeable at a BRIGHTNESS knob setting less 
than one-half. The scroller parameter change is temporary, since an 
•UNLNK or CTRL C restores the previous values. 

Macro Call: .SCROL .baddr 

where: .baddr is the address of the two-word 

scroll parameters buffer. 

Errors: 


No errors are returned. No checking is done on the values of the 
parameters. A zero argument is interpreted to mean that the parameter 
value is not to be changed. A negative argument causes the default 
parameter value to be restored. 


Example: 


.SCROL 

• 

# SC B UP 

(ADJUST SCROLL PARAMETERS 

. 

SCBUFl .BYTE 

5 

(DECREASE « LINES TO 5, 

.BYTE 

0 

(LEAVE INTENSITY UNCHANGED 

.WORD 

300 

(TOP LINE AT Y » 300, 


N.2.10 .START 

The .START request starts the display processor if it was stopped by a 
.STOP directive. If the display processor is running, it is stopped 
first, then restarted. In either case, the subpicture stack is 
cleared and the display processor is started at the top of the 
handler*s internal display file. 

Macro Call: •START 

Errors: 

None. 


N.2.11 .STAT 

The .STAT request transfers the address of a seven-word status buffer 
to the display stop interrupt routine in VTBASE. Once the transfer 
has been made, display processor status data is transferred to the 
buffer by the display stop interrupt routine in VTBASE whenever a 
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.DSTAT or .DHALT instruction is encountered (see Sections N.3.3 and 
N.3.4). The transfer is made only when the buffer flag is clear 
(zero). After the transfer is made, the buffer flag is set non-zero 
and the .DSTAT or .DHALT instruction is replaced by a .DNOP (Display 
NOP) instruction. 

The status buffer must be a seven-word, contiguous block of memory. 
Its contents are the same as the light pen status buffer. For a 
detailed description of the buffer and an explanation of the status 
words, see section N.2.5 and Table N-l. 

Macro Call: .STAT .baddr 

where: .baddr is the address of the status 

buffer receiving the data. 

Errors: 

No errors are indicated. If a buffer was previously set up, the new 
buffer address is replaced as the old buffer address. 


N.2.12 .STOP 

The .STOP request "stops" the display processor. It actually effects 
a stop by preventing the DPU from cycling through any user display 
files. It is useful for stopping the display during modification of a 
display file, a risky task when the display processor is running. 
However, a .BLANK could be equally useful for this purpose, since the 
.BLANK request does not return until the display processor has been 
removed from the user display file being blanked. 

Macro Call: .STOP 

Errors: 

None. 


NOTE 

Since the display processor must cycle 
through the text buffer in the Display 
Monitor in order for console output to 
be processed, the text buffer remains 
visible after a .STOP request is 
processed, but all user files disappear. 


N.2.13 .SYNC/.NOSYN 

The .SYNC and .NOSYN requests provide program access to the power line 
synchronization feature of the display processor. The .SYNC request 
enables synchronization and the .NOSYN request disables it (the 
default case). 

Synchronization is achieved by stopping the display and restarting it 
when the power line frequency reaches a trigger point, e.g., a peak or 
zero-crossing. Synchronization has the effect of fixing the display 
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refresh time. This may be useful in some cases where small amounts of 
material are displayed but the amount frequently changes, causing 
changes in intensity. In most cases, however, using synchronization 
increases flicker. 

Macro Calls: .SYNC 
.NOSYN 

Errors: 

None. 


N.2.14 .TRACK 

The .TRACK request causes the tracking object to appear on the display 
CRT at the position specified in the request. The tracking object is 
a diamond-shaped display figure which is light-pen sensitive. If the 
light pen is placed over the tracking object and then moved, the 
tracking object follows the light pen, trying to center itself on the 
pen. 

The tracking object first appears at a position specified in a 
two-word buffer whose address was supplied with the .TRACK request. 
As the tracking object moves to keep centered on the light pen, the 
new center position is returned to the buffer. A new set of X and Y 
values is returned for each light pen interrupt. 

The tracking object cannot be lost by moving it off the visible 
portion of the display CRT. When the edge flag is set, indicating a 
side of the tracking object is crossing the edge of the display area, 
the tracking object stops until moved toward the center. To remove 
the tracking object from the screen, repeat the .TRACK request without 
arguments. 

The .TRACK request may also include the address of a completion 
routine as the second argument. If a .TRACK completion routine is 
specified, the light pen interrupt handler passes control to the 
completion routine at interrupt level. The completion routine is 
called as a subroutine and the exit statement must be am RTS PC. The 
completion routine must also preserve any registers it may use. 

Macro Call: .TRACK .baddr, .croutine 

where: .baddr is the address of the two-word 

buffer containing the X and Y 
position for the track object. 

.croutine is the address of the completion 
routine. 


Errors: 

None. 

Example: 

See Section N.10. 
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N.2.15 .UNLNK 

The .UNLNK request is used before exiting from a program. In the case 
where the scroller is present, .UNLNK breaks the link, established by 
.LNKRT, between the Display File Handler's internal display file and 
the scroll file in the Display Monitor. The display processor is 
started cycling in the scroll text buffer, and no further graphics may 
be done until the link is established again. In the case where no 
scroller exists, the display processor is simply left stopped. 

Macro Call: .UNLNK 

Errors: 

No errors are returned. An internal link flag is checked to determine 
if the link exists. If it does not exist, the request is ignored. 


N.3 EXTENDED DISPLAY INSTRUCTIONS 

The Display File Handler offers the assembly language graphics 
programmer an extended display processor instruction set, implemented 
in software through the use of the Load Status Register A (LSRA) 
instruction. The extended instruction set includes: subroutine call, 
subroutine return, display status return, display halt, and load name 
register. 


N.3.1 DJSR Subroutine Call Instruction 

The DJSR instruction (octal code is 173400) simulates a display 
subroutine call instruction by using the display stop instruction 
(LSRA instruction with interrupt bits set)• The display stop interrupt 
handler interprets the non-zero word following the DJSR as the 
subroutine return address, and the second word following the DJSR as 
the address of the subroutine to be called. The instruction sequence 
is: 

DJSR 

Return address 
Subroutine address 

Example: 

To call a subroutine SQUARE: 


POINT 

1 POSITION BEAM 

100 

1 AT (100,100) 

100 


DJSR 

ITHEN CAUL SUBROUTINE 

.*« 


SQUARE 

1 TO DRAM A SQUARE 


DRET 

0 

The use of the return address preceding the subroutine address offers 
several advantages. BASIC/GT uses the return address to branch around 
subpicture tag data stored following the subpicture address. This 
structure is described in Section N.5.3. In addition, a subroutine may 
be temporarily bypassed by replacing the DJSR code with a DJMP 
instruction, without the need to stop the display processor to make 
the by-pass. 
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The address of the return address is stacked by the display stop 
interrupt handler on an internal subpicture stack. The stack depth is 
conditionalized and has a default depth of 10. If the stack bottom is 
reached, the display stop interrupt handler attempts to protect the 
system by rejecting additional subroutine calls. In that case, the 
portions of the display exceeding the legal stack depth will not be 
displayed. 


N.3.2 DRET Subroutine Return Instruction 

The DRET instruction provides the means for returning from a display 
file subroutine. It uses the same octal code as DJSR, but with a 
single argument of zero. The DRET instruction causes the display stop 
interrupt handler to pop its subpicture stack and fetch the subroutine 
return address. 

Example: 

SOUARE I LONGV f DR A W A SQUARE 

1001INTX 
3 

311NTX 
100 

10011NTX1MINUSX 
3 

3 JINTX 
1001NJNUSX 

0KET IRETURN FROM SUBPICTURE 

0 


N.3.3 DSTAT Display Status Instruction 

The DSTAT instruction (octal code is 173420) uses the LSRA instruction 
to produce a display stop interrupt, causing the display stop 
interrupt handler to return display status data to a seven-word user 
status buffer. The status buffer must first have been set up with a 
.STAT macro call (if not, the DSTAT is ignored and the display is 
resumed). The first word of the buffer is set non-zero to indicate the 
transfer has taken place, and the DSTAT is replaced with a DNOP 
(display NOP). The first word is the buffer flag and the next six 
words contain name register contents, current subpicture tag, display 
program counter, display status register, display X register, and 
display Y register. After transfer of status data, the display is 
resumed. 


N.3.4 DHALT Display Halt Instruction 

The DHALT instruction (octal code is 173500) operates similarly to the 
DSTAT instruction. The difference between the two instructions is 
that the DHALT instruction leaves the display processor stopped when 
exiting from the interrupt. A status data transfer takes place 
provided the buffer was initialized with a .STAT call. If not, the 
DHALT is ignored. 
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Example: 



.STAT 

*SBUF 

UNIT BUFFER 


MOV 

•OHALT, STPLQC 

IINSERT DHALT 


.INSRT 

pofile 

fDISPLAY THE PICTURE 

ISI 

TST 

8BUF 

1DHALT PROCESSED* 

BEQ 

• 

13 

1 NO, WAIT 

SBUFl 

,BLKW 

7 

I3TATUS BUFFER 

OFILEI 

POINT 


1 POSITION NEAR TOP OF 12" TUBE 


.WORD 
LONG V 

500,1350 

IDRAW A LINE, HAYBE OVER EDGE 


.W0R0 

0,400 

1 IF IT IS A 12" SCOPE, 

STPLOCl 

0N0P 

ORET 

0 


1 STATUS WILL BE RETURNED AT THIS POINT 


N.3.5 DNAME Load Name Register Instruction 

The Display File Handler provides a name register capability through 
the use of the display stop interrupt. When a DNAME instruction 
(octal code is 173520) is encountered, a display stop interrupt is 
generated. The display stop handler stores the argument following the 
DNAME instruction in an internal software register called the "name 
register". The current name register contents are returned whenever a 
DSTAT or DHALT is encountered, and more importantly, whenever a light 
pen interrupt occurs. The use of a "name" (with a valid range from 1 
to 77777) enables the programmer to label each element of the display 
file with a unique name, permitting the easy identification of the 
particular display element selected by the light pen. 

The name register contents are stacked on a subpicture call and 
restored on return from the subpicture. 

Example: 

The SQUARE subroutine with "named" sides: 

SQUARE I DNAME 
10 

LONG V 
100IINTX 
0 

ONAME 
11 

0JINTX 
100 
ONAME 
12 

100JINTXJMINU5X 
0 

DNAME 


INAME IS 
110 

IDRAN A SIDE 


ITHIS SIDE IS NAMED 

mi 

ISTILL IN LONG VECTOR M00E 
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13 

01JNTX 

1001MINUSX 

DRET IRETURN FROM SUBPICTURE 

0 


N.4 USING THE DISPLAY FILE HANDLER 

Graphics programs which intend to use the Display File Handler for 
display processor management can be written in MACRO assembly 
language. The display code portions of the program may use the 
mnemonics described in Section N.7. Calls to the Handler should have 
the format described in Section N.6. 

The Display File Handler is supplied in two pieces, a library of MACRO 
calls and a library containing the Display File Handler modules. 

MACRO Library: VTMAC.MAC 

Display File Handler: VTHDLR.OBJ (consisting of:) 

VTBASE.OBJ 
VTCALl.OBJ 
VTCAL2.OBJ 
VTCAL3.0BJ 
VTCAL4.0BJ 


N.4.1 Assembling Graphics Programs 

To assemble a graphics program using the display processor mnemonics 
or the Display Handler macro calls, the file VTMAC.MAC must be 
assembled with the program, and must precede the program in the 
assembler command string. 

Example: 

Assume PICTUR.MAC is a user graphics program to be assembled. An 
assembler command string would look like this: 

.R MACRO 

*PICTUR=VTMAC,PICTUR 


N.4.2 Linking Graphics Programs 

Once assembled with VTMAC, the graphics program must be linked with 
the Display File Handler, which is supplied as a single concatenated 
object module, VTHDLR.OBJ. The Handler may optionally be built as a 
library, following the directions in N.8.5. The advantage of using the 
library when linking is that the Linker will select from the library 
only those modules actually used. Linking with VTHDLR.OBJ results in 
all modules being included in the link. 

To link a user program called PICTUR.OBJ using the concatenated object 
module supplied with RT-11: 

.R LINK 

*PICTUR=PICTUR,VTHDLR 
* 
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To link a program called PICTUR.OBJ using the VTLIB library built by 
following the directions in N.8.5, be sure to use the Version 2 
Linker: 


.R LINK 

*PICTUR=PICTUR,VTLIB 

* 


VTLIB (Handler Modules) : 


Module 

CSECT 

VTCAL1 

$GT1 

VTCAL2 

$GT2 

VTCAL3 

$GT3 

VTCAL4 

$GT4 

VTBASE 

$GTB 


Contains 

.CLEAR 
.START 
.STOP 
.INSRT 
.REMOV 

.BLANK 
•RESTR 

• LPEN 

.NAME 

.STAT 

.SYNC 

.NOSYN 

.TRACK 

.LNKRT 

•UNLNK 

.SCROL 

Memory resident base module 
containing interrupt handlers 
and internal display file 


To link a display program using overlays, the modules must be 
specified individually. The user must acquire the sources and follow 
the assembly directions in Section N.8. The modules VTCAL1 and VTCAL2 
must be simultaneously resident. For example: 

.R LINK 

*PICTUR=PICTUR,VTBASE/C 
*VTCAL1,VTCAL2,VTCAL3/0:1/C 
*VTCAL4/0:1 

To link a display program to run as a foreground task: 

.R LINK 

*PICTUR=PICTUR,VTLIB/R 


N.5 DISPLAY FILE STRUCTURE 

The Display File Handler supports a variety of display file 
structures, takes over the job of display processor management for the 
programmer, and may be used for both assembly language graphics 
programming and for systems program development. For example, the 
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Handler supports the tagged subpicture file structure used by 
BASIC/GT, as well as simple file structures. These are discussed in 
this section. 


N.5.1 Subroutine Calls 

A subroutine call instruction, with the mnemonic DJSR, is implemented 
using the display stop (DSTOP) instruction with an interrupt. The 
display stop interrupt routine in the Display File Handler simulates 
the DJSR instruction, and this allows great flexibility in choosing 
the characteristics of the DJSR instruction. 

The DJSR instruction stops the display processor and requests an 
interrupt. The DJSR instruction may be followed by two or more words, 
and in this implementation the exact number may be varied by the 
programmer at any time. The basic subroutine call has this form: 

DJSR 

Return Address 
Subroutine Address 

In practice, simple calls to subroutines could look like: 

DJSR 

.WORD .+4 

.WORD SUB 

where SUB is the address of the subroutine. Control will return to 
the display instruction following the last word of the subroutine 
call. This structure permits a call to the subroutine to be easily 
by-passed without stopping the display processor, by replacing the 
DJSR with a display jump (DJMP) instruction: 

DJMP 

.WORD .+4 

.WORD SUB 


A more complex display file structure is possible if the return 
address is generalized: 

.DJSR 

.WORD NEXT 

.WORD SUB 


where NEXT is the generalized return address. This is equivalent to 
the sequence: 

DJSR 

.WORD .+4 

.WORD SUB 

DJMP 

.WORD NEXT 


It is also possible to store non-graphic data such as tags and 
pointers in the subroutine call sequence, such as is done in the 
tagged subpicture display file structure of BASIC/GT. This technique 
looks like: 
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DJSR 

.WORD NEXT 

.WORD SUB 

DATA 

NEXT: 


For simple applications where the flexibility of the DJSR instruction 
described above is not needed and the resultant overhead not desired, 
the Display File Handler (VTBASE.MAC and VTCALL.MAC) can be 
conditionally re-assembled to produce a simple DJSR call. If NOTAG is 
defined during the assembly, the Handler will be configured to support 
this simple DJSR callt 


DJSR 

.WORD SUB 

where SUB is the address of the subroutine. Defining NOTAG will 
eliminate the subpicture tag capability, and with it the tracking 
object, which uses the tag feature to identify itself to the light pen 
interrupt handler. 

Whatever the DJSR format used, all subroutines and the user main file 
must be terminated with a subroutine return instruction. This is 
implemented as a display stop instruction (given the mnemonic DRET) 
with an argument of zero. A subroutine then has the form: 

SUB: Display Code 
DRET 
.WORD 0 


N.5.2 Main File/Subroutine Structure 

A common method of structuring display files is to have a main file 
which calls a series of display subroutines. Each subroutine will 
produce a picture element and may be called many times to build up a 
picture, producing economy of code. If the following macros are 
defined: 


.MACRO CALL <ARG> 

DJSR 

.WORD .+4 

.WORD ARG 

.ENDM 

.MACRO RETURN 

DRET 

.WORD 0 

.ENDM 

then a main file/subroutine file structure would look like: 

jMAIN DISPLAY FILE 

MAIN: Display Code 

CALL SUB1 jCALL SUBROUTINE 1 

Display Code 

CALL SUB2 |CALL SUBROUTINE 2 

I ETC 
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; 

;DISPLAY 
? 

SUB1: 

; 

SUB2: 


RETURN 

SUBROUTINES 

Display Code 
RETURN 

Display Code 
RETURN 


;SUBROUTINE 1 

>SUBROUTINE 2 
;ETC. 


N.5.3 BASIC/GT Subroutine Structure 

An example of another approach to display file structure is the tagged 
subpicture structure used by BASIC/GT. The display file is divided 
into distinguishable elements called subpictures, each of which has 
its own unique tag. 

The subpicture is constructed as a subroutine call followed by the 
subroutine. It is essentially a merger of the main file/subroutine 
structure into an in-line sequence of calls and subroutines. As such, 
it facilitates the construction of display files in real time, one of 
the important advantages of BASIC/GT. 

The following is an example of the subpicture structure. Each 
subpicture has a call to a subroutine with the return address set to 
be the address of the next subpicture. The subroutine called may 
either immediately follow the call, or may be a subroutine defined as 
part of a subpicture created earlier in the display file. This 
permits a subroutine to be used by several subpictures without 
duplication of code. Each subpicture has a tag to identify it and it 
is this tag which is returned by the light pen interrupt routine. To 
facilitate finding subpictures in the display file, they are made into 
a linked list by inserting a forward pointer to the next tag. 


SUB 11 

D J SR 


I START OF SUBPICTURE 1 


. WORD 

SUB2 

INEXT SUBPICTURE 


• WORD 

SUB 1 * 12 

»JUMP TO THIS SUBPICTURE 


.WORD 

1 

1TAG • 1 


.WORD 

SUB2+6 

I POINTER TO NEXT TAG 

» BODY 

OF SUBPICTURE t 

DRET 

e 

1 RETURN FROM 

1 SUBPICTURE 1 

SUB2I 

OJSR 


ISTART SUBPICTURE 2 


. wORD 

SUB3 

>NEXT SUBPICTURE 


.WORD 

SUB2+12 

IJUHP TO THIS SUBPICTURE 


.WORD 

2 

1 TAG • 2 


.WORD 

SUB3+6 

IPTR TO NEXT TAG 


I BODY OF SUBPICTURE i 
DRET 

• WORD 0 
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SUB3I 

UJ5R 

3UB4 

ISTART SUBPICTURE 3 


.WORD 

1 NEXT SUBPICTURE 


.WORD 

SUB 1 * 1 ? 

KOPY SUBPICTURE I 
IFOR THIS SUBPICTURE 


.WORD 

3 

1 BUT T*G IT 3, 


.WORD 

SUBawfe 

IPTR TO NEXT TAG 

SuBfl 1 

D J SR 

• 

• 

• 


ISTART SUBPICTURE 4 
IETC, 

SUMMARY OF 

GRAPHICS 

MACRO CALLS 



Mnemonic 


Function 


Assembly Language 
MACRO Call Expansion (see 

(See Note 1) Note 2) 


.BLANK 

Temporarily blanks 
a user display file. 

.CLEAR 

Initializes handler. 

.INSRT 

Inserts a call to 
user display file 
in handler's master 
display file. 

.LNKRT 

Sets up vectors and 
links display file 
handler to RT-11 


scroller. 


.BLANK .faddr 


.CLEAR 


.INSRT .faddr 


.LNKRT 


.GLOBL $VBLNK 
.IF NB, .faddr 
MOV .faddr, %tl00 
. ENDC 

JSR %t07 f $VBLNK 

.GLOBL $VINIT 
JSR %t07, $VINIT 

.GLOBL $VNSRT 
.IF NB, .faddr 
MOV .faddr, %tOO 
.ENDC 

JSR %t07, $VNSRT 

.GLOBL $VRTLK 
JSR %t07, $VRTLK 


.LPEN 


.NAME 


.NOSYN 


.REMOV 


Sets up light pen 
status buffer. 

.LPEN .baddr 

.GLOBL SVLPEN 
.IF NB, .baddr 
MOV .baddr, %tOO 
.ENDC 

JSR %t07, $VLPEN 

Sets up buffer to 
receive name 
register stack 

contents. 

.NAME .baddr 

.GLOBL $NAME 
.IF NB, .baddr 
MOV .BEDDR, %tOO 
.ENDC 

JSR %t07, $NAME 

Disable power line 
sync. 

.NOSYN 

.GLOBL $NOSYN 

JSR %t07, $NOSYN 

Removes the call to 
a user display file. 

.REMOV .faddr 
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.RESTR 

.SCROL 

.START 

.STAT 

.STOP 

.SYNC 

.TRACK 


.UNLNK 


Unblanks the user 
display file. 


Adjusts monitor 
scroller parameters. 


Starts the display. 


.RESTR .faddr .GLOBL $VRSTR 

IF NB, .faddr 
MOV .faddr, %tOO 
.ENDC 

JSR %t07, $VRSTR 

.SCROL .baddr .GLOBL $VSCRL 

.IF NB, .baddr 
MOV .baddr, %tOO 
runr 

JSR %t07, $VSCRL 


.START 


.GLOBL $VSTRT 
JSR %t07, $VSTRT 


Sets up status 
buffer. 


Stops the display. 


.STAT .baddr .GLOBL $VSTPM 

.IF NB, .baddr 
MOV .baddr, %tOO 
.ENDC 

JSR %t07, $VSTPM 

.STOP .GLOBL $VSTOP 

JSR %t07, $VSTOP 


Enables power line .SYNC 

sync. 


.GLOBL $SYNC 
JSR %t07, $SYNC 


Enables the track 
object. 


.TRACK .baddr, .GLOBL $VTRAK 
.croutine .IF NB, .baddr 

MOV .baddr, %tOO 
.ENDC 

.IF NB, .croutine 
MOV .croutine,- 
(%t06) 

IFF 

CLR-(% t06) 

.ENDC 
.NARG T 
.IF EQ, T 
CLR %tOO 
.ENDC 

JSR %t07, $VTRAK 


Unlinks display .UNLNK .GLOBL $VUNLK 

handler from RT-11 JSR %t07, $VUNLK 

if linked, otherwise 
leaves display stopped. 

NOTE 1 

.baddr Address of data buffer. 


.faddr Address of start of user 

display file. 

.croutine Address of .TRACK completion 
routine. 


N-22 










Display File Handler 


NOTE 2 


The lines preceded by a dot will not be 
assembled. The code they enclose may or 
may not be assembled depending on the 
conditionals. 


N.7 DISPLAY PROCESSOR MNEMONICS 


Mnemonic 


Value 

Function 

CHAR 


100000 

Character Mode 

SHORTV 

SS 

104000 

Short Vector Mode 

LONGV 

ss 

110000 

Long Vector Mode 

POINT 

XX 

114000 

Point Mode 

GRAPHX 

ss 

120000 

Graphplot X Mode 

GRAPHY 

ss 

124000 

Graphplot Y Mode 

RELATV 

ss 

130000 

Relative Point Mode 

INTO 

= 

2000 

Intensity 0 
(Dimmest) 

INTI 

38 

2200 

Intensity 1 

INT2 

S3 

2400 

Intensity 2 

INT3 

Si 

2600 

Intensity 3 

INT4 

SS 

3000 

Intensity 4 

I NT 5 

ss 

3200 

Intensity 5 

INT6 

ss 

3400 

Intensity 6 

INT7 


3600 

Intensity 7 
(Brightest) 

LPOFF 

SI 

100 

Light Pen Off 

LPON 

=* 

140 

Light Pen On 

BLKOFF 

XX 

20 

Blink Off 

BLKON 

- 

30 

Blink On 

LINEO 

a 

4 

Solid Line 

LINE1 

ss 

5 

Long Dash 

LINE 2 

ss 

6 

Short Dash 

LINE 3 

ss 

7 

Dot Dash 

DJMP 

a 

160000 

Display Jump 

DNOP 

ss 

164000 

Display No Operation 

STATSA 

■ 

170000 

Load Status A 
Instruction 

LPLITE 

a 

200 

Light Pen Hit On 

LPDARK 


300 

Light Pen Hit Off 

ITALO 

a 

40 

Italics Off 

I TALI 

* 

60 

Italics On 

SYNC 


4 

Halt and Resume in 
Sync 

STATSB 


174000 

Load Status B 
Instruction 
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Mnemonic 
INCR 

(Vector/Point Mode) 
INTX 


MAXX 

MAXY 

MINUSX 

MINUSY 

(Short Vector Mode ) 

SHIFTX 

MAXSX 
MAXSY 

MISVX 

MISVY 


Value Function 

100 Graphplot Increment 


40000 Intensity Vector or 

Point 

1777 Maximum X Component 

1377 Maximum Y Component 

20000 Negative X Component 

20000 Negative Y Component 


200 

17600 Maximum X Component 

77 Maximum Y Component 

20000 Negative X Component 

100 Negative Y Component 


N.8 ASSEMBLY INSTRUCTIONS 


N•8.1 General Instructions 

All programs can be assembled in 16K, using RT-11 MACRO. All 
assemblies and all links should be error free. The following 
conventions are assumed: 

1. Default extensions are not explicitly typed. These are .MAC 
for source files, .OBJ for assembler output , and .SAV for 
Linker output. 

2. The default device (DK) is used for all files in the example 
command strings. 

3. Listings and link maps are not generated in the example 
command strings. 


N.8.2 VTBASE 

To assemble VTBASE with RT-11 link-up capability: 

.R MACRO 
* VTBAS E=VTB AS E 
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N.8.3 VTCAL1 - VTCAL4 

To assemble the modules VTCAL1 through VTCAL4: 


.R MACRO 
*VTCAL1=VTCAL1 
*VTCAL2 =VTCAL2 
*VTCAL 3=VTCAL 3 
*VTCAL4“VTCAL4 


N.8.4 VTHDLR 

To create the concatenated handler module: 

.R PIP 

* VTHDLR.OBJ=VTCAL1.OBJ,VTCAL2.OBJ,VTCAL3.OBJ,VTCAL4.OBJ,VTBASE.OB J/B 


N.8.5 Building VTLIB.OBJ 
To build the VTLIB library: 
,R LIBR 

*VTLIB»* VTHDLR. OBJ 


N.9 VTMAC 

.NLIST 

i vthac 

t LIBRARY OF MACRO CALLS AMO MNEMONIC DEFINITIONS 
l FOR TmE VT11 DEVICE SUPPORT PACKAGE 

l DEC-il-OVTMA-B-LA 

I COPYRIGhT (C) 1974 

I digital equipment corporation 

I MaYNARO, MASSACHUSETTS 01754 
f MAY 1974 

» THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO 
t CHANGE WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED 
» AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

I DEC ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT 
> MAY APPEAR IN THIS OOCUMENT. 

I DEC ASSUMES NO RESPONSIBILITY FOR THE USE 
I OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT 
» WHICH IS NOT SUPPLIED BY DEC. 

I THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A 
I LICENSE FOR USE ON A SINGLE COMPUTER SYSTEM AND 
I CAN BE COPIED (WITH INCLUSION OF DEC'S COPYRIGHT 
I NOTICE) ONLY FOR USE IN SUCH A SYSTEM, EXCEPT AS MAY 
I OTHERWISE BE PRQVIOED in writing by dec. 
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I VTMAC 15 A LIBRARY OF MACRO CALLS WHICH PROVIDE SUPPORT 
I OF THE VT11 DISPLAY PROCESSOR, THE MACROS PRODUCE CALLS 
I TO THE V T11 DEVICE SUPPORT PACKAGE, USING GLOBAL REFER- 
I ENCES. 

» MACRO TO GENERATE a macro WITH ZERO ARGUMENTS, 

.MACRO MAC0 NAME,CALL 

.macro name 

.GLOBL CALL 
JSR **07,CALL 
.ENDM 
. ENDM 

I macro to generate a macro WITH one argument 

.macro MAC 1 name,call 
.macro name arg 

.IF NB,ARG 

MOV ARG,**00 

.ENDC 

.GLOBL CALL 

JSR **07,CALL 

.ENDM 

.ENDM 

I MACRO TO GENERATE A MACRO WITH TWO OPTIONAL ARGUMENTS 

.MACRO MAC2 NAME,CALL 

.MACRO NAME ARG1,ARG2 

.GLOBL CALL 

.IF NB.ARG1 

MOV ARG1,**O0 

.ENDC 

.IF N8.ARG2 

MOV ARG2,*(**0B) 

.IFF 

CLR -(**06) 

.NARG T 

.IF EQ,T 
CL« **00 

.ENDC 
.ENOC 

JSR X"07,CALL 

.ENDM 

.ENDM 
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i macro library for VT111 


MACS <.CLEAR*, <SVIMT* 

MAC0 <.ST0P*,«SV3T0P* 

MAC0 <. START*,<3VSTRT> 

MAC0 <.SYNC*,«SSYNC* 

MAC0 <,N0SYN>,<$N0SYN> 

MAC0 <,UNLNK*,<SVUNLK* 

MAC l 4,INSRT*,<8VN3RT> 

MAC 1 «.REMOV*,«tSVRMOV* 

MACI <«BLANK*,«3VBLNK* 

MAC l «.RE3TR*,«3VRSTR* 

MACI <,8TAT>,«$V8TPM* 

MAC! «,LPEN*,<8YLPEN> 

MAC! <.3CR0L*,«8V3CRL* 

MACI «,NAME*,«SNAM£* 

MAC2 «, TRACK*,<$VTRAK* 

MAC0 <,LNKRT*,«$VRTLK* 


( MNEMONIC DEFINITIONS FOR THE VTii DISPLAY PROCESSOR 
( 

DJMP*160000 (display jump 

DNOP*164000 (DISPLAY NOP 

DJSR*173400 IDI SPLAY SUBROUTINE CALL 

ORET■173400 (DISPLAY SUBROUTINE RETURN 

DNAME*l7 3520 
DSTAT*173420 

DHALT*17 3500 (STOP DISPLAY AND RETURN STATUS DATA 


I SET NAME REGISTER 
( RETURN STATUS DATA 
F STOP DISPLAY AND RETURN 


I 

CHAR*100000 

shorty*i 04000 
long v »110000 

POINT*l14000 
GRAPHX*120000 
GRAPH Y »124000 
RELATV*130000 
( 

INT0*2000 
I NT 1■2200 
1NT2*2400 
INT3*2600 
INT4*3000 


(CHARACTER MODE 
(SHORT VECTOR MODE 
I LONG VECTOR MODE 
>POINT MOOE 
(GRAPH X MODE 
(GRAPH Y MODE 
(RELATIVE VECTOR MODE 

(INTENSITY 0 


INT5»3200 

INT6*3400 

INT7*3600 

( 

LPOFF*100 

LPON*140 

BLKOFF*20 

BlkON*30 

LINE0*4 

LINEl*5 

LINE2-6 

LINE3»7 


(LIGHT PEN OFF 
(LIGHT PEN ON 
(BLINK OFF 
(BLINK ON 
(SOLID LINE 
(LONG OASH 
(SHORT OASH 
(DOT DASH 


( 
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STATSA«170000 

LPLIT£»200 

LPDARK»300 

ITAU0»«0 

ITAL1*60 

SYNC»« 

I 

STATSB»174000 

INC H•100 

INTX»40000 

MAXX«1777 

MAXY-1377 

MINUSX*20000 

MINU3Y»20000 

MAXSX«17600 

MAX3Y«77 

M18VX»20000 

MJSVY*100 

.LIST 


I LOAD STATUS PEG A 
IINTENSIFY ON LPEN HIT 
IOONM INTENSIFY 
utalics OFF 
IITAUICS ON 
I POWER LINE SYNC 

/LOAD STATUS REG B 
IGRAPH PLOT INCREMENT 
I INTENSIFY VECTOR OR POINT 
IMAXIMUM X INCR. - LONGV 

IMAXIMUM Y INCR, - LONGV 

INEGATIVE X INCREMENT 
INEGATIVE Y INCREMENT 
IMAXIMUM X INCR, • SHORTV 

IMAXIMUM Y INCR. - SHORTV 

INEGATIVE X INCR. - SHORTV 
INEGATIVE Y INCH. - SHORTV 


N. 10 EXAMPLES USING GTON 



example < 

*i 

RT-11 

MACRO VM02"06 9.AUG-74 

PAGE 4 

2 

*1 



1 

> THIS 

.title 

example #1 


0 

4 



EXAMPLE 

USES THE .LPEN 

STATUS BUFFER An!) THE 

5 

ft 



I name 
1 

REGISTER 

TO MODIFY A DISPLAY FILE WITH ThE LIGHT 

0 

7 


000000 

R0»X0 



8 


020001 


*1»X1 



9 


000007 


PC«%7 



10 


000044 


JSW«44 


I JOB STATUS WORD 

11 
12 




•MCAUL 

.TTINR,.EXIT#. 

PRINT 

13 

00000 


starti 

•LNKRT 


ILlNK TO MUNITOR 

1 4 

00004 

100004 


BPL 

IS 

ILlNK UP ERROR? 

15 

00006 



.PRINT 

*EMSG 

I YES# PRINT MESSAGE 

16 

00014 



.EXIT 


IANO EXIT, 

17 

00016 


1 *« 

.SCRQL 

*SCBUF 

1 ADJUST SCROLL 

18 

00026 



.PRINT 

RMSG 


19 

00034 



, INSRT 

RDFILE 

UNSERT DISPLAY FILE 

20 

00044 



.LPEN 

•LBUP 

1SET UP LPEN BUFFER 

21 

00094 

092737 


BIS 

#100# FRjSw 

| SET JSW FOR TTINR 

21 


000100 





21 


000044 





22 

00062 

009767 

ltsti 

TST 

LBUF 

ILIGHT PEN HIT? 

22 


000070 





23 

00066 

001003 


bne 

19 

1 YES 

24 

00070 



.TTINR 


1 NO, ANY TT INPUT? 

23 

00072 

103023 


BCC 

EXIT 

1 YES. EXIT 

26 

00074 

000772 


BR 

LTST 

1N0, LOOP AGAIN 

27 

00076 

016777 

l$l 

MOV 

12# FlPTR 

IRESTORE PREVIOUS CODE 

27 


000074 





27 


000102 





28 

00104 

016701 


MQV 

LBUF*2 » R1 

iget NAME vauue 


N-28 



Display File Handler 


28 

000050 



29 00110 

005301 

use 

R1 

30 00112 

006301 

asl 

R1 

31 00114 

060701 

add 

PC , R1 

32 00116 

062701 

ADD 

rdtabl-., 

32 

000062 



33 00122 

011167 

MOV 

(Rl) f IPTR 

33 

000060 



34 00126 

016777 

MQV 

I1MIPTR 

34 

000042 



34 

000052 



35 00134 

005067 

ClR 

LBUF 

35 

000016 



36 




37 00140 

000750 

b« 

ltst 

38 00142 

022700 EXIT! 

CMP 

*»12,H0 

36 

000012 



39 00146 

001345 

BNE 

LTST 

40 00190 


# (JNLNK 


41 00154 


.EXIT 


42 00156 

LBUF 1 

• BLKN 

7 

43 00174 

103370 Ill 

• aIQPQ 

Char j int 5i 

44 00176 

103160 121 

• «0*D 

CHAR11NT4I 

45 00200 

000252'QTABLI 

• «0*D 

01,02,03 

45 00202 

000272' 



EXAMPLE #1 RT-11 

MACRO VM02-06 9-Al 

45 00204 

000312' 



46 




47 00206 

000252'IPTRJ 

. WORD 

01 

48 00210 

000002 SCBUFl 

• WORD 

2 

49 00212 

001000 

.WORD 

1000 

50 00214 

041 EMSGI 

.ASCI2 

/ 1 ERROR 17 

50 00215 

105 



50 00216 

122 



30 00217 

122 



50 00220 

117 



50 00221 

122 



50 00222 

041 



50 00223 

000 



51 

.EVEN 



52 00224 

105 MSG| 

.ASCIZ 

7EXAMPLE * 

52 00225 

130 



52 00226 

101 



52 00227 

U» 



52 00230 

120 



52 00231 

U4 



52 00232 

105 



52 00233 

040 



52 00234 

043 



52 00235 

061 



52 00236 

000 



53 


.EVEN 


54 

1 



55 

1 DISPLAY FILE 

FOR EXAMPLE 

56 

I 



57 00240 

114000 DFlLEl 

POINT 



JSUBTRACT Qme 
MULTIPLY By TWO 
I USE TO INUE X 
TUFF TABLE OTABl. 

I MOVt AODR INTO IPTR 

MODIFY THAT cooe 

f CLEAR BUFFER FlAU TO 

TENABLE ANOTHER lp hit, 
I LOOP AGAIN 
ILINE FEED? 

MO, GET another 
IUNLINK FROM MONITOR 

»LP£N STATUS BUFFER 
IBLKONJLPON 
[BLKOFFILPON 

itable of display file 


9«AUG»74 PAGE 4+ 


fLOCATIONS TO be MODIFIED 
;PREVIOUS LOCATION MODIFIED 
ISCROLL LINE COUNT 

iscroll top y pos. 

TERROR MESSAGE 


II.D, MESSAGE 


38 00242 BB0108 

59 00244 000500 

60 00246 173520 

61 00290 000001 

62 00252 103160 01 * 


100 

500 

UNAME 

I 

CHAR1BLK0FFUNT41LP0N 
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63 

00254 

117 


.ASCII /ONE./ 

63 

00233 

116 



63 

00236 

103 



63 

00237 

056 


POINT 

64 

00260 

114000 


65 

00262 

000100 


100 

66 

00264 

000300 


300 

67 

00266 

173320 


ONAME 

68 

00278 

000002 


2 

69 

00272 

103160 

021 

char i blkoff iI nT41lpon 

70 

00274 

124 


.ASCII /TWO,/ 

70 

00273 

127 



70 

00276 

117 



70 

00277 

056 


POINT 

71 

00300 

114000 


72 

00302 

000100 


100 

73 

00304 

000100 


100 

74 

00306 

173320 


UNAME 

75 

00310 

000003 


3 

76 

00312 

103160 

031 

CHARJBLKOFFllNT4lLPON 

77 

00314 

124 


.ASCII /THREE,/ 

77 

00313 

110 




EXAMPLE *»1 RT-li MACRO VM02-06 9-AUG-74 PAGE 4* 

77 00016 122 

77 00317 103 

77 00320 103 

77 00321 056 

76 00322 173400 ORET 

79 00324 000000 0 

80 000000* .END START 



9 


EXAMPLE Ml RT-11 MACRO VM02-06 9-AUG-74 PAGE 4+ 

SYMBOL TABLE 


BLKOFF* 

000020 

BLKON 

V 

000030 

CHAR 

■ 

100000 

dfile 

000240R 

ohalt 

i 

173500 

DJMP 

■ 

160000 

OJSR * 

173400 

ONAME 

« 

173520 

ONOP 

* 

164000 

dret • 

173400 

OSTAT 

■ 

173420 

DTABL 


000200R 

Di 

000252R 

02 


0002/2R 

D3 


000312R 

EMSG 

000214R 

EXIT 


000142R 

CRAPHX* 

120000 

GRAPMyi 

124000 

1NCR 


000100 

I NT X 

s 

040000 

iNTa • 

002000 

INTI 


002200 

INT2 

* 

002400 

INT 3 ■ 

002600 

INT4 


003000 

INT5 

■ 

003200 

iNTe • 

003400 

1NT7 


003600 

IPTR 


000206R 

ITAL0 • 

000040 

ITALl 


000060 

11 


00017 4R 

12 

0001 76R 

JSW 


000044 

LBUF 


000156R 

LINE* • 

000004 

LINE1 


000005 

LINE2 

■ 

004006 

LINES • 

000007 

LONGV 


110000 

LPOAHK* 

000300 

LPCITE" 

000200 

LPOFF 


000100 

LPON 

■ 

000140 

LTST 

000062R 

MAXSX 


017600 

maxsy 

E 

000077 

M A X X « 

001777 

MAX Y 


001377 

MINUSX* 

020004 

MINUSY* 

020000 

MISVX 


020000 

MISVY 

■ 

000100 

MSG 

000224R 

PC 

0X000007 

POINT 

S 

114000 

RELATV* 

130000 

R 0 

■X 000000 

R 1 

*X00000t 

SCBJF 

000210R 

short v 


104000 

start 


000000 R 

STATSA* 

170000 

STATSB 


174000 

SYNC 

* 

000004 

SVLPEN* 

****** 6 

4VNSRT 


****** G 

JVHTLKo 

****** 

SVSCRL* 

****** Q 

svunlk 


****** G 





, ABS, 000000 000 

000326 001 

ERRORS UtTfccTfcOt 0 
FREE CURE* 13117, HURDS 




MANE*1,LP|«VTmaC,MANEX1 
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EXAMPLE P2 


RTM1 MACRO VM02-06 9-AUG-74 PAGE 4 


2 

3 

4 

5 

6 
7 


.TITLE EXAMPLE #2 
I 

I this example uses the tracking object and the track 
i completion routine to cause a vector to follow 

1 THE LIGHT PEN FROM A SET point AT (500,500). 

I 


a 


000000 


R0'X0 



9 


000001 


*nxt 



10 


000006 


SP*%6 



11 


000007 


PC«%7 



12 




. MC ALL 

.EXIT,.TTYIN, 

.PRINT 

13 

00000 


STARTI 

.LNKRT 


JLlNK TO MONITOR 

14 

00004 

100004 


BPL 

IS 

ILlNK UP ERROR? 

IS 

00006 



.PRINT 

PEMSG 

I YES, INFORM USER 

16 

00014 



.EXIT 


JAND EXIT 

17 

00016 


IS» 

.IN3RT 

PDFILE 

iinseht display file 

IB 

00026 



.TRACK 

ptbuf,ptcom 

IDISPlAY TRACK OBJECT 

19 

00042 

004767 


JSR 

PC,WAIT 

JWAIT FOR <CR* 

19 


000006 





20 

00046 



.UNLNK 


JUNLINK FROM MONITOR 

21 

00052 



.EXIT 



22 

00054 


WAIT! 

.TTYIN 


1 GET CHAR, FROM TTY 

23 

00060 

022/00 


CMP 

P12,H0 

1L1NE FEED? 

23 


000012 





24 

00064 

001373 


bne 

WAIT 

;no, get another 

23 

00066 

000207 


RTS 

PC 


26 

000/0 

000500 

TBUFI 

.WORD 

500,500 

;TRALK BUFFER InITED TO 

26 

00072 

000000 





27 






ISTART TRACK AT (600,500) 

26 



1 




29 



> TRACK 

COMPLETION ROUTINE ENTERED AT INTERRUPT LEVEL 

30 



1 FROM 

DISPLAY 

FILE HANDLER WITH DISPLAY STOPPED. 

31 



1 USED 

TO UPDATt DISPLAY FILE 

with data from TbuF. 

32 



1 




33 

000/4 

010146 

TCOMI 

MOV 

R1,• ISP) 

ISAVE Rl 

34 

00076 

016701 


MOV 

TBUF,Rl 

1 NEW X 

34 


177766 





35 

00102 

166/01 


SUB 

OX, R1 

I NEW X - OLD X 

33 


000052 





36 

00106 

100003 


BPL 

IS 

IPOSITIVE DIFFERENCE? 

37 

00110 

005401 


NEG 

R1 

»N0, SO MAKE POSITIVE 

38 

00112 

052701 


BIS 

PMINUSX,R1 

;BUT SET MINUS BIT 

38 


020000 





39 

00116 

052701 

IS* 

BIS 

PINTX,R1 

j also set intensify bit 

39 


040000 





40 

00122 

010167 


MOV 

R1,DX 

ITHEN STORE in dFILE. 

40 


000040 





41 

00126 

016701 


MOV 

TBUF*2,R1 

1 NEW Y 

41 


177740 





42 

00132 

166701 


SUB 

0 Y, R1 

|NEW Y - OLD Y 

42 


000024 





43 

00136 

100003 


BPL 

2S 

IPOSITIVE DIFFERENCE? 

44 

00140 

005401 


NEG 

R1 

|NO,Su make POSITIVE 

45 

00142 

052/01 


BIS 

PMINUSX»Ri 

I and SET minus bit 

45 


020000 





46 

00146 

010167 

2 $ 1 

MOV 

Rt,DY 

ITHEN STORE IN DFILE 

46 


000016 
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EXAMPLE *2 RT-U MACRO VM02-06 9-AUG-74 PAGE 4+ 


MOV (SP)♦,R1 

RTS PC 

I 

t OISPLAV FILE FOR EXAMPLE #2 


47 00192 012901 
46 00194 000207 

49 

50 

51 I 

52 00156 H4000 OFILEI 

53 00160 000500 OX f 

54 00162 000500 OYI 

55 00164 113000 

56 00166 000000 OX> 

57 00170 000000 0Y * 

58 00172 173400 

59 00174 000000 

60 00176 123 EMSGI 

60 00177 117 

60 00200 122 
60 00201 122 
60 00202 131 

60 00203 054 

60 00204 040 

60 00205 124 

60 00206 110 


POINT 

500 

500 

LQNGV1INT4 
•WORD 0 
.WORD 0 
URET 
0 

•asciz /sorry, there 


60 00207 105 
60 00210 122 
60 00211 105 
60 00212 040 
60 00213 123 
60 00214 led 
60 00215 103 
60 00216 115 
60 00217 123 
60 00220 040 
60 00221 124 
60 00222 117 
60 00223 040 
60 0022« 102 
60 00225 105 
60 00226 040 
60 00227 101 
60 00230 040 
60 00231 120 
60 00232 122 
60 00233 117 
60 00234 102 
60 00235 114 
60 00236 105 


60 00237 1l5 

60 00240 000 

61 .EVEN 

62 000000' .END START 


I REST ORE R1 

I EX IT FROM COMPLETION ROUTINE 


I SET POINT AT 

I (500,500) 

I OR AM A VECTOR 

^initially nowhere 

10ISPLAY FILE EnO 
SEEMS TO BE A PROBLEM/ 
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EXAMPLE 

#2 RT-li 

MACRO VM02 

-06 9-AUG-74 

PAGE 4* 


symbol TABLE 





BLKOPFi 

000020 

BLKON 4 

000030 

CHAR • 

100000 

DFlLt 

0001 SSR 

ohalt ■ 

173500 

OJMP ■ 

160000 

DJSR ■ 

173400 

ONAME 4 

173320 

DNOP * 

164000 

DRET * 

173400 

OSTAT 4 

173420 

OX 

000166R 

DY 

000170R 

EMSG 

000176R 

GRAPHX* 

120000 

GRARMy* 

124000 

1NCR 4 

000100 

IN T X * 

040000 

INT0 i 

002000 

INTI 4 

002200 

INT2 * 

002400 

INT3 • 

002600 

INT4 4 

003000 

INT5 * 

303200 

INTg 4 

003400 

INT7 4 

003600 

ITAL0 * 

000040 

ITALi • 

000060 

LINE0 ■ 

000004 

LINE1 * 

000005 

LINE2 • 

000006 

LINES ■ 

000007 

LONGV * 

110000 

lpdaRk* 

000300 

LPLITE* 

000200 

LPOFF * 

000100 

lpon ■ 

000140 

MAXSX ■ 

017600 

MAXSY * 

000077 

MAXX 4 

001777 

MAXY ■ 

001377 

MINUSX* 

020000 

MINUSY4 

020000 

MISVX 4 

020000 

MIS V Y s 

000100 

ox 

000160R 

OY 

000162R 

PC * 

X000007 

POINT * 

114000 

RELATV* 

130000 

R0 *: 

*000000 

R1 «X*B00I01 

SHORTY* 

104000 

SP *: 

*000006 

START 

000000 R 

5TATSA* 

170000 

STATS8* 

174000 

SYNC • 

000004 

TBUF 

000070R 

TCUM 

000074R 

WAIT 

000094R 

S VN3R T■ 

****** G 

SVRTLK* 

****** j 

$VTR*X« 

****** G 

SVUNLA4 

****** G 




, AS&, 0000100 000 
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APPENDIX 0 


SYSTEM SUBROUTINE LIBRARY 


0.1 INTRODUCTION 

The RT-11 FORTRAN System Subroutine Library (SYSLIB) is a collection 
of FORTRAN-callable routines which allow a FORTRAN user to utilize 
various features of RT-11 Foreground/Background (F/B) and Single-Job 
(SJ) Monitors. SYSLIB also provides various utility functiqns, a 
complete character string manipulation package, and 2-word integer 
support. SYSLIB is provided as a library of object modules to be 
combined with FORTRAN programs at link-time. 

The user of SYSLIB should be familiar with Chapters 1, 2, and 9 of 
this manual. This appendix assumes that FORTRAN users are familiar 
with the PDP-11 FORTRAN Language Reference Manual and the RT-ll/RSTS/E 
FORTRAN IV User's Guide. 


The following are some of the functions provided by SYSLIB. 

• Complete RT-11 I/O facilities, including synchronous, 
asynchronous, and completion-driven modes of operation. 
FORTRAN subroutines may be activated upon completion of an 
input/output operation. 

• Timed scheduling of asynchronous subjobs (completion 
routines). (F/B only) 

• Complete facilities for interjob communication between 
Foreground and Background jobs (F/B only). 

• FORTRAN interrupt service routines. 

• Complete timer support facilities, including timed suspension 
of execution (F/B only), conversion of different time formats, 
and time-of-day information. These timer facilities support 
either 50- or 60-cycle clocks. 

• All auxiliary input/output functions provided by RT-11, 
including the capabilities of opening, closing, renaming, 
creating, and deleting files from any device. 

• All monitor-level informational functions, such as job 
partition parameters, device statistics, and input/output 
channel statistics. 

• Access to the RT-11 Command String Interpreter (CSI) for 
acceptance and parsing of standard RT-11 command strings. 

• A character string manipulation package supporting 
variable-length character strings. 

• INTEGERM support routines that allow 2-word integer 
computations. 

SYSLIB allows the FORTRAN user to write almost all application 
programs completely in FORTRAN with no assembly language coding. 
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Assembly language programs may also utilize SYSLIB routines (see 
Section 0.1.3) . 


0.1.1 Conventions and Restrictions 

In general, the SYSLIB routines were written for use with RT-11 V2B 
and FORTRAN IV VlB. The use of this SYSLIB package with prior 
versions of RT-11 or FORTRAN will lead to unpredictable results. 

Programs using IPEEK, IPOKE, and/or ISPY to access FORTRAN, monitor, 
hardware, or other system specific addresses are not guaranteed to run 
under future releases or on different configurations. Suitable care 
should be taken with this type of coding to document precisely the use 
of these access functions and to check a referenced location's usage 
against the current documentation. 

The following must be considered when coding a FORTRAN program that 
uses SYSLIB. 

1. Various functions in the SYSLIB package return values that 
are of type integer, real, and double precision. If the user 
specifies an IMPLICIT statement that changes the defaults for 
external function typing, he must explicitly declare the type 
of those SYSLIB functions that return integer or real 
results. Double precision functions must always be declared 
to be type DOUBLE PRECISION (or REAL*8). Failure to observe 
this requirement will lead to unpredictable results. 

2. All names of subprograms external to the routine being coded 
that are being passed to scheduling calls (such as ISCHED, 
ITIMER, IREADF, etc.) must be specified in an EXTERNAL 
statement in the FORTRAN program unit issuing the call. 

3. Certain arguments (noted as such in the individual routine 
descriptions) to SYSLIB calls must be located in such a 
manner as to prohibit the RT-11 USR (User Service Routine) 
from swapping over them at execution time. This is 
accomplished by issuing a SET USR NO SWAP command before the 
job is entered, by using the /U switch at compile time, or by 
assuring that the routine argument is located in the memory 
image in such a way as to not be swapped over. The latter 
may be accomplished by changing the order of the object 
modules and libraries as specified to the linker. If the USR 
is swapping, it swaps over the first 2K of the program. The 
default case, for example, swaps the USR at 1000 octal to 
11000 octal; arguments being passed to the USR must be kept 
out of this area. (See Section 0.1.3 for further 
information.) 

4. Quoted-string literals are useful as arguments of calls to 
routines in the SYSLIB package, notably the character string 
routines. These literals are allowed in subroutine calls 
(i.e., those invoked by the CALL statement), but they are 
explicitly prohibited in function calls (i.e., those invoked 
by the appearance of the function name followed by an 
argument list in an expression). See Sections 0.1.2 and 
0.2.4 for further information. 

5. Certain restrictions apply to completion or interrupt 
routines; see Section 0.2.1 for these restrictions. 
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0.1.2 Calling SYSLIB Subprograms 

SYSLIB subprograms are called in the same manner as user-written 
subroutines. SYSLIB includes both FUNCTION subprograms and SUBROUTINE 
subprograms. FUNCTION subprograms receive control by means of a 
function reference, represented in this appendix as: 

i = function name ({arguments}) 

SUBROUTINE subprograms are invoked by means of a CALL statement, i.e., 
CALL subroutine name { (arguments)} 

All routines in SYSLIB may be called as FUNCTION subprograms if the 
return value is desired, or as SUBROUTINE subprograms if no return 
value is desired. For example, the LOCK subroutine can be referenced 
as either: 

CALL LOCK 

or 

I = L0CK() 

Note that routines that do not explicitly return function results will 
produce meaningless values if referenced as functions. In the 
following descriptions, the more common usage (function or subroutine) 
is shown. 


0.1.3 Using SYSLIB with MACRO 

The calling sequence is standard for all subroutines, including 
user-written FORTRAN subprograms and assembly language subprograms. 
SYSLIB routines may be used with MACRO programs by passing control to 
the SYSLIB routine with the following instruction: 

JSR PC,routine 

Register five points to an argument list having the following format: 


R5 


undefined 


# of arguments 


address of arg. #1 


address of arg. #2 


address of arg. #n 
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Control is returned to the calling program by use of the instruction: 


RTS PC 

The following is an example of calling a SYSLIB function from an 
assembly language routine. 

.GLOBL JMUL ;GLOBAL FOR JMUL 


MOV #LIST,R5 
JSR PC,JMUL 
CMP #-2,R0 
BEQ OVRFL 


POINT R5 TO ARG LIST 
CALL JMUL 

CHECK FOR OVERFLOW 
BRANCH IF ERROR 


LIST: 

.WORD 

3 


.WORD 

OPRl 


.WORD 

0PR2 


.WORD 

RESULT 

OPRl: 

.WORD 

100 


.WORD 

0 

OPR 2: 

.WORD 

10 


.WORD 

10 

RESULT: 

. BLKW 
.END 

2 


ARG LIST,3 ARGS 

ADDR OF 1ST ARG 

ADDR OF 2ND ARG 

ADDR OF 3RD ARG 

LOW-ORDER VALUE OF 1ST ARG 

HIGH-ORDER VALUE OF 1ST ARG 


LOW-ORDER VALUE OF 2ND ARG 

HIGH-ORDER VALUE OF 2ND ARG 

2-WORD RESULT (LOW ORDER, HIGH ORDER) 


The following routines can be used only with FORTRAN: 

GETSTR 

IASIGN 

ICDFN 

IFETCH 

IGETC 

ILUN 

INTSET 

IQSET 

IRCVDF 

IREADF 

ISCHED 

ISDATF 

ISPFNF 

ITIMER 

IWRITF 

PUTSTR 

SECNDS 


User-written assembly language programs that call SYSLIB subprograms 
must preserve any pertinent registers before calling the SYSLIB 
routine and restore the registers, if necessary, upon return. 


Function subprograms return a single result in the registers. The 
register assignments for returning the different variable types are: 


Integer, Logical functions 


result in RO 
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Real functions - high-order result in RO, low-order result in Rl 

Double Precision functions - result in R0-R3, lowest order result 

in R3 


Complex functions - high-order real result in RO, low-order real 

result in Rl, high-order imaginary result in 
R2, low-order imaginary result in R3 


ser written assembly language routines which interface to the FORTRAN 
Time ? ystem (° TS ) must be aware of the location of the RT-11 
USR (User Service Routine). If a user routine requests a USR function 
IENTER ' LOOKUP) , or if the USR is invoked by the FORTRAN OTS, 
the USR will be swapped into memory if it is nonresident. The FORTRAN 
OTS is designed so that the USR can swap over it. User routines must 
be written to allow the USR to swap over them or must be located 
outside the region of memory into which the USR will swap. 


User interrupt service routines and completion routines, because of 
their asynchronous nature, must be further restricted to be located 
where the USR will not swap. The USR (if in a swapping state) will 
always swap over the area of memory that starts at the program initial 
stack pointer address; the USR occupies 2K words. Interrupt and 
completion routines (and their data areas) must not be located in this 
area. The best way to accomplish this is to examine the link map, 
determine whether the USR will swap over an assembly language or 
FORTRAN asynchronous routine, and, if so, change the order of object 
modules and libraries as specified to the linker. Continue this 
process until a suitable arrangement is obtained. 


To remove these restrictions, the user must make the USR resident 
either by specifying the /U switch to the FORTRAN compiler (when' 
compiling a program to be run in the background of F/B or under S-J) 
or by issuing the SET USR NOSWAP command before executing the program. 


0.1.4 Running a FORTRAN Program in the Foreground 

The FRUN monitor command must be modified to include various SYSLIB 
functions. Section G.l explains the formula used to allocate the 
needed space when running a FORTRAN program as a foreground job. This 
formula: 

x = (l/2{378+(29*N)+(R-136)+A*512)}} 
must be modified for SYSLIB functions as follows: 

The IQSET function requires the formula to include additional space 
for queue elements (qleng) to be added to the queue: 

x = { l/2{378+(29*N) + (R-136)+A*512) }}+{7 *qleng} 

The ICDFN function requires the formula to include additional space 
for the integer number of channels (num) to be allocated. 

x = (l/2{378+(29*N) + (R-136)+A*512)}} + {6 *num} 

The INTSET function requires the formula to include additional space 
for the number of INTSET calls (INTSET) issued in the program. 
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{1/2 {378+ (29*N) +(R-136)+A*512}}+{25*INTSET} 


Any SYSLIB calls, including INTSET, that invoke completion routines 
must include 64(10) words plus the number of words needed to allocate 
the second record buffer (default is 68(10) words). The length of the 
record buffer is controlled by the /R switch to the FORTRAN compiler. 
If the /R switch is not used, the allocation in the formula must be 
132(10) words. 


x = {l/2{378+(29*N)+(R-136)+A*512}}+{64+R/2} 

If the /N option does not allocate enough space in the foreground on 
the initial call to a completion routine, the following message 
appears: 

?ERR 0, NON-FORTRAN ERROR CALL 


This message also appears if there is not enough free memory for the 
background job or if a completion routine in the Single-Job monitor is 
activated during another completion routine. In the latter case, the 
job aborts. F/B should be used for multiple active completion 

routines. 


0.1.5 Linking with SYSLIB 

SYSLIB is provided on the distribution media as a file of concatenated 
object modules (SYSF4.0BJ). If this file is linked directly with the 
FORTRAN program, all SYSLIB modules will be included whether they are 
used or not. For example: 

^R LINK 

iPROG=PROG,SYSF4/F 

A library can be created by using the librarian to transform SYSF4 
into a library file (SYSLIB) as follows: 

a R LIBR 
*SYSLIB=SYSF4 

When a library is used, only the modules called will be linked with 
the program. For example: 

iR LINK 

,£PROG=PROG, SYSLIB/F 

The following example links the object module EXAMPL.OBJ into a single 
save image file EXAMPL.SAV and produces a load map file on LP:. 
SYSLIB and the default FORTRAN library (FORLIB.OBJ) are searched for 
any routines that are not found in other object modules. 

j_R LINK 

1EXAMPL,LP:=EXAMPL,SYSLIB/F 

If the FORTRAN library is explicitly specified in the command string, 
SYSLIB must precede it, i.e., 

^R LINK 

iTEST=TEST,SYSLIB,FPULIB 
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is an acceptable command string, but the following is not: 
*TEST=TEST,FPULIB,SYSLIB 


0.2 TYPES OF SYSLIB SERVICES 

Ten types of services are available to the user through SYSLIB. These 
are: 

1. File-Oriented Operations 

2. Data Transfer Operations 

3. Channel-Oriented Operations 

4. Device and File Specifications 

5. Timer Support Operations 

6. RT-11 Service Operations 

7. INTEGERM Support Functions 

8. Character String Functions 

9. Radix-50 Conversion Operations 

10. Miscellaneous Services 

Table 0-1 alphabetically summarizes the SYSLIB subprograms in each of 
these categories. Those marked with an asterisk (*) are allowed only 
in a Foreground/Background environment. 


Table 0-1 

Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

File-Oriented Operations 

CLOSEC 

0.3.3 

Closes the specified channel. 

IDELET 

0.3.19 

Deletes a file from the specified device. 

IENTER 

0.3.22 

Creates a new file for output. 

IRENAM 

0.3.37 

Changes the name of the indicated file to a 
new name. 

LOOKUP 

0.3.66 

Opens an existing file for input and/or output 
via the specified channel. 

Data Transfer Functions 

*IRCVD 

*IRCVDC 

*IRCVDF 

*IRCVDW 

0.3.35 

Receives data. Allows a job to read messages 
or data sent by another job in an F/B environ¬ 
ment. The four modes correspond to the IREAD, 
IREADC, IREADF, and IREADW modes. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

Data Transfer Functions 

(cont.) 

IREAD 

0.3.36 

Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. No special action is taken 
upon completion of I/O. 

IREADC 

0.3.36 

Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. Upon completion of the 
read, control transfers to the assembly 
language routine specified in the IREADC 
function call. 

IREADF 

0.3.36 

Transfers data via the specified channel to a 
memory buffer and returns control to the user 
program when the transfer request is entered 
in the I/O queue. Upon completion of the 
read, control transfers to the FORTRAN 
subroutine specified in the IREADF function 
call. 

IREADW 

0.3.36 

Transfers data via the specified channel to a 
memory buffer and returns control to the 
program only after the transfer is complete. 

*ISDAT 

*ISDATC 

*ISDATF 

*ISDATW 

0.3.41 

Allows the user to send messages or data to 
the other job in an F/B environment. The four 
modes correspond to the IWRITE, IWRITC, 
IWRITF, and IWRITW modes. 

ITTINR 

0.3.47 

Inputs one character from the console 

keyboard. 

ITTOUR 

0.3.48 

Transfers one character to the console 

terminal. 

IWAIT 

0.3.51 

Waits for completion of all I/O on a specified 
channel. (Commonly used with the IREAD and 
IWRITE functions.) 

IWRITC 

0.3.52 

Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. Upon completion of the write, 
control transfers to the assembly language 
routine specified in the IWRITC function call. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

Data Transf 

er Functions (cont.) 

IWRITE 

0.3.52 

Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. No special action is taken upon 
completion of the I/O. 

IWRITF 

0.3.52 

Transfers data via the specified channel to a 
device and returns control to the user program 
when the transfer request is entered in the 
I/O queue. Upon completion of the write, 
control transfers to the FORTRAN subroutine 
specified in the IWRITF function call. 

IWRITW 

0.3.52 

Transfers data via the specified channel to a 
device and returns control to the user program 
only after the transfer is complete. 

*MWAIT 

0.3.68 

Waits for messages to be processed. 

PRINT 

0.3.69 

Outputs an ASCII string to the console 

terminal. 

Channel-Oriented Operations 

ICDFN 

0.3.14 

Defines additional I/O channels. 

*ICHCPY 

0.3.15 

Allows access to files currently open in the 
other job's environment. 

*ICSTAT 

0.3.18 

Returns the status of a specified channel. 

IFREEC 

0.3.24 

Returns the specified RT-11 channel to the 
available pool of channels for the FORTRAN I/O 
system. 

IGETC 

0.3.25 

Allocates an RT-11 channel and marks it in use 
to the FORTRAN I/O system. 

ILUN 

0.3.27 

Returns the RT-11 channel number with which a 
FORTRAN logical unit is associated. 

IREOPN 

0.3.38 

Restores the parameters stored via an ISAVES 
function and reopens the channel for I/O. 

ISAVES 

0.3.39 

Stores five words of channel status 

information into a user-specified array. 

PURGE 

0.3.70 

Deactivates a channel. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

Device and E 

'ile Specifications 

IASIGN 

0.3.13 

Sets information in the FORTRAN logical unit 

table. 

ICSI 

0.3.17 

Calls the RT-11 CSI in special mode to decode 
file specifications and switches. 

Timer Suppoi 

ct Operations 

CVTTIM 

0.3.5 

Converts a 2—word internal format time to 
hours, minutes, seconds, and ticks. 

GTIM 

0.3.9 

Gets time of day. 

*ICMKT 

0.3.16 

Cancels an unexpired ISCHED, ITIMER, or MRKT 
request. 

*ISCHED 

0.3.40 

Schedules the specified FORTRAN subroutine to 
be entered at the specified time of day as an 
asynchronous completion routine. 

*ISLEEP 

0.3.42 

Suspends main program execution of the running 
job for a specified amount of time; 
completion routines continue to run. 

*ITIMER 

0.3.45 

Schedules the specified FORTRAN subroutine to 
be entered as an asynchronous completion 
routine when the time interval specified has 
elapsed. 

*ITWAIT 

0.3.49 

Suspends the running job for a specified 
amount of time; completion routines continue 
to run. 

*IUNTIL 

0.3.50 

Suspends the main program execution of the 
running job until a specified time-of-day; 
completion routines continue to run. 

JTIME 

0.3.63 

Converts hours, minutes, seconds, and ticks 
into 2-word internal format time. 

*MRKT 

0.3.67 

Marks time, i.e., schedules an assembly 
language routine to be activated as an 
asynchronous completion routine after a 
specified interval. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

Timer Support Operations (cont.) 

SECNDS 

0.3.80 

Returns the current system time in seconds 
past midnight minus the value of a specified 
argument. 

TIMASC 

0.3.84 

Converts a specified 2-word internal format 
time into an 8-character ASCII string. 

TIME 

0.3.85 

Returns the current system time-of-day as an 
8-character ASCII string. 

RT-11 Services 

CHAIN 

0.3.2 

Chains to another program (in the background 
job only). 

^DEVICE 

0.3.6 

Specifies actions to be taken on normal or 
abnormal program termination, such as turning 
off interrupt enable on foreign devices, etc. 

GTJB 

0.3.10 

Returns the parameters of this job. 

IDSTAT 

0.3.21 

Returns the status of the specified device. 

IFETCH 

0.3.23 

Loads a device handler into memory. 

IQSET 

0.3.33 

Expands the size of the RT-11 monitor queue 
from the free space managed by the FORTRAN 
system. 

ISPFN 

ISPFNC 

ISPFNF 

ISPFNW 

0.3.43 

Issues special function requests to various 
handlers, e.g., magtape. The four modes 
correspond to the IWRITE, IWRITC, IWRITF, and 
IWRITW modes. 

*ITLOCK 

0.3.46 

Indicates whether the USR is currently in use 
by another job and performs a LOCK if the USR 
is available. 

LOCK 

0.3.65 

Makes the RT-11 monitor User Service Routine 
(USR) permanently resident until an UNLOCK 
function is executed. A portion of the user's 
program is swapped out to make room for the 
USR if necessary. 

RCHAIN 

0.3.74 

Allows a program to access variables passed 
across a chain. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

RT-11 Services (cont.) 

RCTRLO 

0.3.75 

Enables output to the terminal by cancelling 
the effect of a previously typed CTRL 0, if 
any. 

♦RESUME 

0.3.77 

Causes the main program execution of a job to 
resume where it was suspended by a SUSPND 
function call. 

♦SUSPND 

0.3.83 

Suspends main program execution of the running 
job; completion routines continue to execute. 

UNLOCK 

0.3.88 

Releases the USR if a LOCK was performed; the 
user program is swapped in if required. 

INTEGERM Support Functions 

AJFLT 

0.3.1 

Converts a specified INTEGERM value to REAL*4 
and returns the result as the function value. 

DJFLT 

0.3.7 

Converts a specified INTEGERM value to REAL*8 
and returns the result as the function value. 

IAJFLT 

0.3.12 

Converts a specified INTEGERM value to REAL*4 
and stores the result. 

IDJFLT 

0.3.20 

Converts a specified INTEGERM value to REAL*8 
and stores the result. 

IJCVT 

0.3.26 

Converts a specified INTEGERM value to 

INTEGERM. 

JADD 

0.3.53 

Computes the sum of two INTEGERM values. 

JAFIX 

0.3.54 

Converts a REAL *4 value to INTEGERM. 

JCMP 

0.3.55 

Compares two INTEGERM values and returns an 
INTEGERM value that reflects the signed 
comparison result. 

JDFIX 

0.3.56 

Converts a REAL *8 value to INTEGERM. 

JDIV 

0.3.57 

Computes the quotient and remainder of two 
INTEGERM values. 

JICVT 

0.3.58 

Converts an INTEGERM value to INTEGERM. 


(continued on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 


Function 

Call 

Section 

Purpose 

INTEGERM i 

Support Functions (cont.) 

JJCVT 

0.3.59 

Converts 2-word internal time format to 

INTEGERM format, and vice versa. 

JMOV 

0.3.60 

Assigns an INTEGERM value to a variable. 

JMUL 

0.3.61 

Computes the product of two INTEGERM values. 

JSUB 

0.3.62 

Computes the difference between two INTEGERM 
values. 

Character S 

tring Functions 

CONCAT 

0.3.4 

Concatenates two variable-length strings. 

GETSTR 

0.3.8 

Reads a character string from a specified 
FORTRAN logical unit. 

INDEX 

0.3.28 

Returns the location in one string of the 
first occurrence of another string . 

INSERT 

0.3.29 

Replaces a portion of one string with another 
string. 

ISCOMP 

0.3.78 

Compares two character strings. 

IVERIF 

0.3.89 

Indicates whether characters in one string 
appear in another. 

LEN 

0.3.64 

Returns the number of characters in a 

specified string. 

PUTSTR 

0.3.71 

Writes a variable-length character string on a 
specified FORTRAN logical unit. 

REPEAT 

0.3.76 

Concatenates a specified string with itself to 
provide an indicated number of copies and 
stores the resultant string. 

SCOMP 

0.3.78 

Compares two character strings. 

SCOPY 

0.3.79 

Copies a character string from one array to 
another. 

STRPAD 

0.3.81 

Pads a variable-length string on the right 
with blanks to create a new string of a 
specified length. 


(concluded on next page) 
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Table 0-1 (cont.) 
Summary of SYSLIB Subprograms 



Routines requiring the USR (see Section 9.2.5) differ between the 
Single-Job and F/B Monitors. The following functions require the use 
of the USR: 

CLOSEC . , _ 

GETSTR (only if first I/O operation on logical unit) 

ICDFN (Single-Job only) 
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ICSI 

IDELET 

IDSTAT 

IENTER 

IFETCH 

IQSET 

IRENAM 

ITLOCK (only if USR is not in use by the other job) 

LOCK (only if USR is in a swapping state) 

LOOKUP 

PUTSTR (only if first I/O operation on logical unit) 

Certain requests require a queue element taken from the same list as 
the I/O queue elements. These are: 

IRCVD/IRCVDC/IRCVDF/IRCVDW 
IREAD/IREADC/IREADF/IREADW 
ISCHED 

ISDAT/ISDATC/ISDATF/ISDATW 

ISLEEP 

ISPFN/ISPFNC/ISPFNF/ISPFNW 

ITIMER 

ITWAIT 

IUNTIL 

IWRITC/IWRITE/IWRITF/IWRITW 

MRKT 

MWAIT 


0.2.1 Completion Routines 

Completion routines are subprograms that execute asynchronously with a 
main program. A completion routine is scheduled to run as soon as 
possible after the event for which it has been waiting has completed 
(e.g., the completion of an I/O transfer, or the lapsing of a 
specified time interval). All completion routines of the current job 
have higher priority than other parts of the job? therefore, once a 
completion routine becomes runnable because of its associated event, 
it interrupts execution of the job and continues to execute until it 
relinquishes control. 

Completion routines are handled differently in the Single-Job and the 
F/B versions of RT-11. In the Single-Job version, completion routines 
are totally asynchronous and can interrupt one another. In F/B, 
completion routines do not interrupt each other but are queued and 
made to wait until the correct job is running. (For further 
information on completion routines, see Sections 9.2.8 and 0.1.4.) 

A FORTRAN completion routine can have a maximum of two arguments: 

SUBROUTINE crtn { ( iargl,iarg2)} 

where: iargl is equivalent to RO on entry to an assembly 

language completion routine. 

iarg2 is equivalent to R1 on entry to an assembly 

language completion routine. 

If an error occurs in a completion routine or in a subroutine at 
completion level, the error handler will trace back normally through 
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to the original interruption of the main program. Thus the traceback 
is shown as though the completion routine were called from the main 
program and lets the user know where the main program was executing if 
a fatal error occurs. 

Certain restrictions apply to completion routines, i.e., those 
routines that are activated by the following calls:* 

INTSET 

IRCVDC 

IRCVDF 

IREADC 

IREADF 

ISCHED 

ISDATC 

ISDATF 

ISPFNC 

ISPFNF 

ITIMER 

IWRITC 

IWRITF 

MRKT 

These restrictions are: 

1. The first subroutine call that references a FORTRAN 
completion routine must be issued from the main program. 

2. No channels may be allocated (by calls to IGETC) or freed (by 
calls to IFREEC) from a completion routine. Channels to be 
used by completion routines should be allocated and placed in 
a COMMON block for use by the routine. 

3. The completion routine may not perform any call which 
requires the use of the USR, e.g., LOOKUP and IENTER. See 
Section 0.2 for a list of SYSLIB functions that call the USR. 

4. Files to be operated upon in completion routines must be 
opened and closed by the main program. There are, however, 
no restrictions on the input or output operations that may be 
performed in the completion routine. If many files must be 
made available to the completion routine, they may be opened 
by the main program and saved for later use (without tying up 
RT-11 channels) by the ISAVES call. The completion routine 
may later make them available by reattaching the file to a 
channel with an IREOPN call. 

5. FORTRAN subprograms are reusable but not reentrant. A given 
subprogram can be used many times as a completion routine or 
as a routine in the main program but a subprogram executing 
as main program code will not work properly if interrupted at 
the completion level. This restriction applies to all 
subprograms that can be invoked at the completion level and 
can be active at the same time in the main program. 

6. Only one completion function should be active at any time 
under the Single-Job Monitor (see Section 0.1.4). 

7. Assembly language completion routines must be exited via an 
RTS PC. 
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8. FORTRAN completion routines must be exited by execution of a 
RETURN or END statement in the subroutine* 


0.2.2 Channel-Oriented Operations 

An RT-11 channel being used for input/output with SYSLIB must be 
allocated in one of the following two ways: 

1. The channel is allocated and marked in use to the FORTRAN I/O 
system by a call to IGETC and is later freed by a call to 
IFREEC• 

2. An ICDFN call is issued to define more channels (up to 256). 
All channels numbered greater than 17 (octal) can be freely 
used by the programmer? the FORTRAN I/O system uses only 
channels 0 through 17 (octal). 

Channels must be allocated in the main program routine or its 
subprograms, not in routines that are activated as the result of I/O 
completion events or ISCHED or ITIMER calls. 


0.2.3 INTEGERM Support Functions 

INTEGERM variables are allocated two words of storage. INTEGERM 
values are stored in two's complement representation. The first word 
(lower address) contains the low-order part of the value, and the 
second word (higher address) contains the sign and the high-order part 
of the value. The range of numbers supported is -2 31 +1 to 2 31 -1. 

Note that this format differs from the 2-word internal time format 
which stores the high-order part of the value in the first word and 
the low-order part in the second. The JJCVT function (Section 0.3.59) 
is provided for conversion between the two internal formats. 

Integer and real arguments to subprograms are indicated in the 
following manner in this appendix. 

i = INTEGERM arguments 
j = INTEGERM arguments 
a = REALM arguments 
d = REALM arguments 

When the DATA statement is used to initialize INTEGERM variables, it 
must specify both the low- and high-order parts, i.e., 

INTEGERM J 
DATA J/3/ 

only initializes the first word. 

The correct way to initialize an INTEGERM variable to a constant 
(e.g., 3) is shown below: 

INTEGERM J 
INTEGERM 1(2) 

EQUIVALENCE (J,I) 

DATA 1/3,0/ UNITIALIZE J TO 3 
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If initializing an INTEGERM variable to a negative value (e.g., -4) , 

the high-order (second word) part must be the continuation of the 
two's complement of the low-order part. For example: 

INTEGERM J 
INTEGERM 1(2) 

EQUIVALENCE (J,I) 

DATA I/-4,-1/ !INITIALIZE J TO -4 


The following form is suitable for INTEGERM arguments to subprograms: 
INTEGERM J (2) 

DATA J/3,0/ !LOW-ORDER,HIGH-ORDER 


0.2.4 Character String Functions 

The SYSLIB character string functions and routines provide 
variable-length string support for RT-11 FORTRAN. SYSLIB calls are 
provided to perform the following character string operations: 

• Read character strings from a specified FORTRAN logical unit 
(GETSTR). 

• Write character strings to a specified FORTRAN logical unit 
(PUTSTR). 

• Concatenate variable-length strings (CONCAT). 

• Return the position of one string in another (INDEX). 

• Insert one string into another (INSERT). 

• Return the length of a string (LEN). 

• Repeat a character string (REPEAT). 

• Compare two strings (SCOMP). 

• Copy a character string (SCOPY). 

• Pad a string with rightmost blanks (STRPAD). 

• Copy a substring from a string (SUBSTR). 

• Perform character modification (TRANSL). 

• Remove trailing blanks (TRIM). 

• Verify the presence of characters in a string (VERIFY). 

Strings are stored in L0GICAL*1 arrays which are defined and 
dimensioned by the FORTRAN programmer. Strings are stored in these 
arrays as one character per array element plus a zero element to 
indicate the current end of the string (ASCIZ format). 

The length of a string may vary at execution time, ranging from zero 

characters in length to one less than the size of the array which 

stores the string. The maximum size of any string is 32767 
characters. Strings may contain any of the 7-bit ASCII characters 
except null (0), as the null character is used to mark the end of the 
string. Bit 7 of each character must be off (0); therefore, the 
valid characters are those whose decimal representations range from 1 
to 127, inclusive. 

The ASCII code used in this string package is the same as that 

employed by FORTRAN for A-type FORMAT items, ENCODE/DECODE strings, 
and object-time FORMAT strings. ASCIZ strings in the form used by 

these routines are generated by the FORTRAN compiler whenever quoted 
strings are used as arguments in the CALL statement. Note that a null 
string (a string containing no characters) may be represented in 
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FORTRAN by a variable or constant of any type which contains the value 
zero, or by a LOGICAL variable or constant with the .FALSE. value. 

The SYSLIB user should ensure that a string never overflows the array 
that contains it by being aware of the length of the string result 
produced by each routine. In many routines where the result string 
length may vary or is difficult to determine/ an optional integer 
argument may be specified to the subroutine to limit the length. In 
the sections describing the character string routines, this argument 
is called "len". The length of an output string is limited 
to the value specified for "len" plus one (for the null terminator); 
therefore the array receiving the result must be at least "len" plus 
one elements in size. 

The optional argument "err" may be included when "len" is specified. 
"Err" is a logical variable which should be initialized by the FORTRAN 
program to the .FALSE, value. If a string function is given the 
arguments "len" and "err", and "len" is actually used to limit the 
length of the string result, then "err" is set to the .TRUE. value. 
If "len" is not used to truncate the string, "err" is unchanged, i.e., 
remains .FALSE.. 

"Len" and "err" are always optional arguments. "Len" may appear 
alone; however, "len" must appear if "err" is specified. 

Several routines use the concept of character position. Each 
character in a string is assigned a position number which is one 
greater than the position of the character immediately to its left. 
The first character in a string is in position one. 


0.2.4.1 Allocating Character String Variables — A 1-dimensional 
L0GICAL*1 array may be used to contain a single string whose length 
may vary from zero characters to one less than the dimensioned length 
of the array. For example: 

L0GICAL*1 A(45) !ALLOCATE SPACE FOR STRING VARIABLE A 

The preceding example allows array A to be used as a string variable 
that can contain a string of 44 or less characters. Similarly, a 
2-dimensional L0GICAL*1 array may be used to contain a 1-dimensional 
array of strings. Each string in the array may have a length up to 
one less than the first dimension of the the L0GICAL*1 array. There 
may be as many strings as the number specified for the second 
dimension of the L0GICAL*1 array, e.g., 

L0GICAL*1 W(21,10) iALLOCATE AN ARRAY OF STRINGS 

The preceding example creates a string array W which has 10 string 
elements, each of which may contain up to 20 characters. String I in 
array W is referenced in subroutine or function calls as W(1,I). 

A 2-dimensional string array may be allocated, e.g., 

LOGICAL*l T(14,5,7) !ALLOCATE A 5 BY 7 STRING ARRAY 

In the preceding example, each string in array T may vary in length to 
a maximum of 13 characters. String I,J of the array may be referenced 
as T(1,I,J). Note that T is the same as T(l,l,l). This dimensioning 
process may be continued to create string arrays of up to six 
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dimensions (represented by LOGICAL*l arrays of up to seven 
dimensions). 


0.2.4.2 Passing Strings to Subprograms — The L0GICAL*1 arrays which 
contain strings may be placed in a COMMON block and referenced by any 
or all routines with a similar COMMON declaration. However, care 
should be taken when a L0GICAL*1 array is placed in a COMMON block, 
for if such an array has an odd length, it may cause all succeeding 
variables in the COMMON block to be assigned odd addresses. This 
situation will be detected by the RT-11 FORTRAN compiler, resulting in 
a warning message if the /W switch is specified. 

A L0GICAL*1 array has an odd length only if the product of its 
dimensions is odd, e.g., 

L0GICAL*1 B(10,7) I(10*7)=70; EVEN LENGTH 

LOGICAL*l H (21) 121 IS ODD? ODD LENGTH 

If odd length arrays are to be placed in a COMMON block, they should 
either be placed at the end of the block or they should be paired to 
result in an effective even length. For example: 

COMMON A1,A2,A3(10) ,H (21) 1PLACE ODD-SIZED ARRAY AT END 

or 

COMMON A1,A2,H(21) ,H1(7) ,A3(10) 1PAIR ODD-SIZED ARRAYS H AND Hi 

Note that these cautions apply only to LOGICAL*l variables and arrays. 

The second method of passing strings to subprograms is through 
arguments and formal parameters. A single string may be passed by 
using its array name as an argument. For example: 

LOGICAL*l A(21) 1 STRING VARIABLE "A", 20 CHARACTERS MAXIMUM 

CALL SUBR(A) 1PASS STRING A TO SUBROUTINE SUBR 

If the maximum length of a string argument is unknown in a subroutine 
or function, or if the routine is used to handle many different length 
strings, the dummy argument in the routine should be declared as a 
LOGICAL*l array with a dimension of one, e.g., LOGICAL*l ARG(l). In 
this case, the string routines will correctly determine the length of 
ARG whenever it is used, but it will not be possible to determine the 
maximum size string which may be stored in ARG. If a 
multi-dimensional array of strings is passed to a routine, it must be 
declared in the called program with the same dimensions as were 
specified in the calling program. 


NOTE 

The length argument specified in many of 
the character string functions refers to 
the maximum length of the string 
excluding the necessary null byte 
terminator. The length of the LOGICAL*l 
array to receive the string must be at 
least one greater than the length 
argument. 
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0.2.4.3 Using Quoted-String Literals — Quoted-strings may be used as 
arguments to any of the string routines that are invoked by the CALL 
statement. They cannot be used for routines invoked as functions. 
For example: 

CALL SCOMP(NAME, 1 DOE , JOHN'/M) 

compares the string in the array NAME to the constant string DOE , JOHN 
and sets the value of the integer variable M accordingly. Although 
the above form of the routine reference is permitted/ the statement: 

M=ISC0MP(NAME/'DOE/ JOHN') 

is not allowed since the routine is not invoked by the CALL statement 
and includes a quoted-string literal. 


0.3 LIBRARY FUNCTIONS AND SUBROUTINES 

This section presents all SYSLIB functions and subroutines in 
alphabetic order. To reference these subprograms by usage , see Table 
0 - 1 . 


AJFLT 


0.3.1 AJFLT 

The AJFLT function converts an INTEGER*4 value to a REALM value and 
returns that result as the function value. 

Form: a = AJFLT (jsrc) 

where: jsrc is the INTEGERM variable to be converted. 

Function Results: 

The function'result is the REALM value that is the result of the 
operation. 

Example: 

The following example converts the INTEGERM value contained in JVAL 
to single precision (REALM ), multiplies it by 3.5/ and stores the 
result in VALUE. 

REAL*4 VALUE/AJFLT 
INTEGERM JVAL 


VALUE=AJFLT(JVAL)*3.5 
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CHAIN 


0.3.2 CHAIN 

The CHAIN subroutine allows a background program (or any program in 
the Single-Job system) to transfer control directly to another 
background program, passing it specified information. CHAIN cannot 
be called from a completion or interrupt routine. CHAIN does not 
close any of the FORTRAN logical units. When CHAINing to any other 
program, the user should explicitly close the opened logical units 
with calls to the CLOSE routine. Any USEREX routine specified to 
the FORTRAN run-time system will not be executed if a CHAIN is 
accomplished. 

Form: CALL CHAIN (dblk,var,wcnt) 


where: dblk 


var 


went 


is the address of a 4-word Radix-50 
descriptor of the file specification for 
the program to be run. (See the FORTRAN 
Language Reference Manual , Section 2.2.8.) 

is the first variable in a sequence of 
variables with increasing memory addresses to 
be passed between programs in the chain 
parameter area (absolute locations 510 up to 
700). A single array or a COMMON block (or 
portion of a COMMON block) is a suitable 
sequence of variables. 

is a word count (up to 60 words) specifying 
the number of words (beginning at var) to be 
passed to the called program. 


If the size of the chain parameter area is insufficient, it may be 
increased by specifying the /B (bottom) switch to LINK for both the 
program executing the CHAIN call and the program receiving control. 

The data passed may be accessed through a call to the RCHAIN routine 
(see Section 0.3.74). For more information on chaining to other 
programs, see Section 9.4.2. 

Errors: 

None. 
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Example: 


The following example transfers control from the main program to 
PROG.SAV, on DTO, passing it variables. 

REAL*4 PROGNM 1RAD50 FOR PROGRAM NAME 

COMMON /BLK1/ A,B,C,D IDATA TO BE PASSED 

DATA PROGNM/6RDTOPRO,6RG SAV/ 


CALL CHAIN(PROGNM,A,8) 


!RUN DTO:PROG.SAV 


CLOSEC 


0.3.3 CLOSEC 

The CLOSEC subroutine terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated 
device must be in memory. CLOSEC cannot be called from a completion 
or interrupt routine. 


Form: CALL CLOSEC (chan) 

where: chan is the channel number to be closed. This 

argument must be located so that the USR 
cannot swap over it. 

A CLOSEC or PURGE must eventually be issued for any channel opened for 
either input or output. A CLOSEC call specifying a channel that is 
not open is ignored. 

A CLOSEC performed on a file that was opened via an IENTER causes the 
device directory to be updated to make that file permanent. If the 
device associated with the specified channel already contains a file 
with the same name and extension, the old copy is deleted when the new 
file is made permanent. A CLOSEC on a file opened via LOOKUP does not 
require any directory operations. 

When an entered file is CLOSECed, its permanent length reflects the 

highest block of the file written since the file was entered; for 

example, if the highest block written is block number 0, the file is 

given a length of 1; if the file was never written, it is given a 
length of 0. If this length is less than the size of the area which 
was allocated at IENTER time, the unused blocks are reclaimed as an 
empty area on the device. 

Errors: 

CLOSEC does not generate any errors. If the device handler for the 
operation is not in memory, a fatal monitor error is generated. 
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Example: 

The following example creates and processes a 56-block file. 
REAL*4 DBLK(2) 

DATA DBLK/6RSY0NEW,6RFILDAT/ 

DATA ISIZE/56/ 


ICHAN=IGETC() 

IF(ICHAN.LT.0) GOTO 100 

IF(IENTER(ICHAN,DBLK,ISIZE)-1) 10,110,120 


CALL CLOSEC(ICHAN) 

CALL IFREEC(ICHAN) 

CALL EXIT 

100 STOP 'NO AVAILABLE CHANNELS' 

110 STOP 'CHANNEL ALREADY IN USE' 

120 STOP 'NOT ENOUGH ROOM ON DEVICE' 
END 


CONCAT 


0.3.4 CONCAT 


The CONCAT subroutine is used to concatenate character strings. 
Form: CALL CONCAT (a,b,out{,len{,err}}) 


where: a 


is the array containing the left string. 


b is the array containing the right string. 

out is the array into which the concatenated 

result is placed. This array must be at 
least one element longer than the maximum 
length of the result string (i.e., one 
greater than the value of len, if specified). 


len is the integer number of characters 

representing the maximum length of the output 
string. The effect of len is to truncate the 
output string to a given length, if 

necessary. 

err is the Logical error flag set if the output 

string is truncated to the length specified 
by len. 
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The string in array "a" immediately followed on the right by the 
string in array "b" and a terminating null character replaces the 
string in array "out". Any combination of string arguments is allowed 
so long as "b" and "out" do not specify the same array. Concatenation 
stops either when a null character is detected in "b" or when the 
number of characters specified by "len" have been moved. 

If either the left or right string is a null string, the other string 
is copied to "out". If both are null strings, then "out" is set to a 
null string. The old contents of "out" are lost when this routine is 
called. 

Errors: 

Error conditions are indicated by "err", if specified. If "err" is 
given and the output string would have been longer than "len" 
characters, then "err" is set to .TRUE.; otherwise, "err" is 
unchanged. 

Example: 

The following example concatenates the string in array STR and the 
string in array IN and stores the resultant string in array OUT. OUT 
cannot be larger than 29 characters. 

LOGICAL*! IN (30) ,OUT(30) ,STR(7) 


CALL CONCAT(STR,IN,OUT,29) 


CVTTIM 


0.3.5 CVTTIM 

The CVTTIM subroutine converts a 2-word internal format time to hours, 
minutes, seconds, and ticks. 

Form: CALL CVTTIM (time,hrs,min,sec,tick) 

where: time is the 2-word internal format time to be 

converted. If time is considered as a 
2-element INTEGER*2 array, then: 

time (1) is the high-order time, 

time (2) is the low-order time. 


hr s 


is the integer number of hours. 
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is the integer number of minutes. 

is the integer number of seconds. 

is the integer number of ticks (1/60 of a 
second for 60-cycle clocks; 1/50 of a second 
for 50-cycle clocks). 

Errors: 

None. 

Example: 

INTEGER*4 ITIME 


min 

sec 

tick 


CALL GTIM(ITIME) ‘GET CURRENT TIME-OF-DAY 

CALL CVTTIM(ITIME,IHRS,IMIN,ISEC,ITCK) 

IF(IHRS.GE.12) GOTO 100 ITIME FOR LUNCH 


DEVICE 


0.3.6 DEVICE (F/B only) 

The DEVICE subroutine allows the user to set up a list of addresses to 
be loaded with specified values when the program is terminated. If a 
job terminates or is aborted with a CTRL C from the terminal, this 
list is picked up by the system and the appropriate addresses are set 
up with the corresponding values. 

This function is primarily designed to allow user programs to load 
device registers with necessary values. In particular, it is used to 
turn off a device's interrupt enable bit when the program servicing 
the device terminates. 

Only one address list may be active at any given time; hence, if 
multiple DEVICE calls are issued, only the last one has any effect. 
The list must not be modified by the FORTRAN program after the DEVICE 
call has been issued, and the list must not be located in an overlay 
or an area over which the USR will swap. 

Form: CALL DEVICE (ilist) 

where: ilist is an integer array containing address/value 

pairs, terminated by a zero word. On program 
termination, each value is moved to the 
corresponding address. 

For more information on loading values into device registers, see the 
assembly language .DEVICE request. Section 9.4.11. 
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Errors 


None 


Example 


INTEGER*2 IDR11(3) 

DATA IDR11(1)/"167770/ 
DATA IDR11(2)/0/ 

DATA IDR11(3)/0/ 

CALL DEVICE(IDR11) 


!DEVICE ARRAY SPEC 
!DR11 CSR ADDRESS (OCTAL) 

!VALUE TO CLEAR INTERRUPT ENABLE 
iAND END-OF-LIST FLAG 
!SET UP FOR ABORT 


DJFLT 


0.3.7 DJFLT 

The DJFLT function converts an INTEGERM value into a REAL*8 (DOUBLE 
PRECISION) value and returns that result as the function value. 

Form: d = DJFLT (jsrc) 


where: jsrc 


specifies the INTEGERM variable which is to 
be converted. 


Notes: 

If DJFLT is used, it must be explicitly defined (REALM DJFLT) or 
implicitly defined (IMPLICIT REALM (D)) in the FORTRAN program. If 
this is not done, its type will be assumed as REAL*4 (single 
precision). 

Function Results: 

The function result is the REAL*8 value that is the result of the 
operation. 

Example: 


INTEGERM JVAL 
REALM DJFLT ,D 


D=DJFLT(JVAL) 
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GETSTR 


0.3.8 GETSTR 

The GETSTR subroutine reads a formatted ASCII record from a specified 
FORTRAN logical unit into a specified array. The data is truncated 
(trailing blanks removed) and a null byte is inserted at the end to 
form a character string. 

GETSTR can be used in main program routines or in completion routines 
but cannot be used in both at the same time. If GETSTR is used in a 
completion routine, it cannot be the first I/O operation on the 
specified logical unit. 

Form: CALL GETSTR (lun ,out,len{ ,err }) 


where: 

lun 

is the integer FORTRAN logical unit number of 
a formatted sequential file from which the 
string is to be read. 


out 

is the array which is to receive the string? 
this array must be one element longer than 
len. 


len 

is the integer number representing the 

maximum length of the string to be input. 


err 

is the Logical error flag that is set to 
.TRUE. if the string specified by "out" 


exceeds the value of "len" in length; err 
must be present if the input string can 
exceed "len". 


Errors: 

Error conditions are indicated by "err". If "err" is given and the 
output string was truncated to the length specified by "len", then 
"err" is set to .TRUE.? otherwise, "err" remains unchanged. 

Example: 

The following example reads a string of up to 80 characters from 
logical unit 5 into the array STRING. 

LOGICAL*! STRING(81),ERR 


CALL GETSTR(5,STRING,80,ERR) 
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GTIM 


0.3.9 GTIM 

THE GTIM subroutine allows user programs to access the current time of 
day. The time is returned in two words and is given in terms of clock 
ticks past midnight. If the system does not have a line clock, a 
value of zero is returned. If an RT-11 monitor TIME command has not 
been entered, the value returned will be the time elapsed since the 
system was bootstrapped rather than the time of day. 

Form: CALL GTIM (itime) 

where: itime is the 2-word area to receive the time of day. 

The high-order time is returned in the first word, the low-order time 
in the second word. The SYSLIB routine CVTTIM (Section 0.3.5) can be 
used to convert the time into hours, minutes, seconds and ticks. 
CVTTIM performs the conversion based on the monitor configuration word 
for 50- or 60-cycle clocks (see Section 9.2.6). Under an F/B Monitor, 
the time-of-day is automatically reset after 24:00 when a GTIM is 
executed; under the Single-Job Monitor, it is not. 

Errors: 

None. 

Example: 


INTEGERM JTIME 

CALL GTIM(JTIME) 


GTJB 


0.3.10 GTJB 

The GTJB subroutine passes certain job parameters back to the user 
program. 
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Form: CALL GTJB (addr) 

where: addr is an 8-word area to receive the job 

parameters. This area, considered as an 
8-element INTEGER*2 array, has the following 
format: 

addr(1) 

addr (2) 
addr (3) 
addr (4) 
addr (5) 
addr (8) 

For more information on passing job parameters, see the assembly 
language .GTJB request. Section 9.4.17. 

Errors: 

None. 

Example: 

INTEGER*2 PARAMS(8) 

CALL GTJB(PARAMS) 

IF(PARAMS(1).EQ.O) TYPE 99 
99 FORMAT (' THIS IS THE BACKGROUND JOB 1 ) 


job number. (0=Background, 

2=Foreground) 

high memory limit 

low memory limit 

beginning of I/O channel space 

reserved for future use 


IADDR 


0.3.11 IADDR 

The IADDR function returns the 16-bit absolute memory address of its 
argument as the integer function value. 

Form: i = IADDR (arg) 

where: arg is the variable, constant, or expression 

whose memory address is to be obtained. 


Errors: 

None. 

Example: 

IADDR can be used to find the address of an assembly language global 
area. For example: 

EXTERNAL CAREA 
J=IADDR(CAREA) 
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IAJFLT 


0.3.12 IAJFLT 

The IAJFLT function converts an INTEGERM value to a REAL*4 value and 
stores the result. 

Form: i = IAJFLT (jsrc,ares) 

where: jsrc is the INTEGERM variable to be converted. 

ares is the REALM variable or array element to 

receive the converted value. 

Function Results: 

The function result indicates the following: 


i = -2 


Significant digits were lost during 
conversion. 


the 


= -1 

Normal 

return; 

the 

result 

is 

= 0 

Normal 

return; 

the 

result 

is 

= 1 

Normal 

return; 

the 

result 

is 


Example: 


INTEGERM JVAL 
REALM RESULT 


99 



IF(IAJFLT(JVAL,RESULT).EQ.-2) TYPE 99 

FORMAT (' OVERFLOW IN INTEGERM TO REAL CONVERSION') 
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IASIGN 


0.3.13 IASIGN 


The IASIGN function sets information in the FORTRAN logical unit table 
(overriding the defaults) so that the specified information is used 
when the FORTRAN Object Time System (OTS) opens the logical unit. 
This function can be used with ICSI (see Section 0.3.17) to allow a 
FORTRAN program to accept a standard CSI input specification. IASIGN 
must be called before the unit is opened, i.e., before any READ, 
WRITE, PRINT, TYPE, or ACCEPT statements are executed that reference 
the logical unit. 

Form: i = IASIGN (lun,idev{,ifilex{,isize{,itype}}}) 

where: lun is an INTEGERS variable, constant, or 

expression specifying the FORTRAN logical 
unit for which information is being 
specified. 

idev is a 1-word Radix-50 device name? this can 

be the first word of an ICSI input or output 
file specification. 


ifilex is a 3-word Radix-50 filename and extension? 

this can be words 2 through 4 of an ICSI 
input or output file specification. 


isize is the length (in number of blocks) to 

allocate for an output file? this can be the 
fifth word of an ICSI output specification. 
If zero, the larger of either one-half the 
largest empty segment or the entire second 
largest empty segement is allocated (see 
Section 9.4.13). If the value specified for 
length is -1, the entire largest empty 
segment is allocated. 


itype is an integer value determining the optional 

attributes to be assigned to the file. This 
value is obtained by adding the values that 
correspond to the desired operations: 


1 use double buffering for output 

2 open the file as a temporary file 

4 perform a lookup on the file (otherwise, 

the first FORTRAN I/O operation 
determines how the file is opened) 
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8 expand carriage control information (see 
Notes below) 

16 do not expand carriage control 
information 

32 file is read-only 


Notes: 

Expanded carriage control information applies only to formatted output 
files and means that the first character of each record is used as a 
carriage control character when processing a write operation to the 
given logical unit. The first character is removed from the record 
and converted to the appropriate ASCII characters to simulate the 
requested carriage control. 

If carriage control information is not expanded, the first character 
of each record is unmodified and the FORTRAN OTS outputs a line feed, 
followed by the record, followed by a carriage return. 

If carriage control is unspecified, the FORTRAN OTS sends expanded 
carriage control information to the terminal and line printer and 
sends unexpanded carriage control information to all other devices and 
files. See the PDP-11 FORTRAN Language Reference Manual, Section 6.3, 
for further carriage control information. 

Function Results: 

i = 0 Normal return. 

<> 0 The specified logical unit is already in use or 

there is no space for another logical unit 
association. 

Example: 

The following example creates an output file on logical unit 3 using 
the first output file given to the RT-11 command string interpreter 
(CSI), sets it up for double buffering, creates an input file on 
logical unit 4 based on the first input file specification given to 
the RT-11 CSI, and makes it available for read-only access. 

INTEGERS SPEC (39) 

REALM EXT (2) 

DATA EXT/6RDATDAT,6RDATDAT/ !DEFAULT EXTENSION IS DAT 


10 IF(ICSI(SPEC,EXT,,,0).NE.0) GOTO 10 

C 

C DO NOT ACCEPT ANY SWITCHES 
C 

CALL IASIGN(3,SPEC(1) ,SPEC(2) ,SPEC(5) ,1) 
CALL IASIGN(4,SPEC(16) ,SPEC(17) ,0,32) 
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ICDFN 


0.3.14 ICDFN 

The ICDFN function increases the number of input/output channels. 
Note that ICDFN defines new channels; the previously-defined channels 
are not used. Thus, an ICDFN for 20 channels (while the 16 original 
channels are defined) causes only 20 I/O channels to exist; the space 
for the original 16 is unused. The space for the new channel area is 
allocated out of the free space managed by the FORTRAN system. 


Form: i = ICDFN (num) 

where: num is the integer number of channels to be 

allocated. The number of channels must be 
greater than 16 and can be a maximum of 256. 
SYSLIB can use all new channels greater than 
16 without a call to IGETC; the FORTRAN 
system input/output uses only the first 16 
channels. This argument must be positioned 
so that the USR cannot swap over it. 

Notes: 

1. ICDFN cannot be issued from a completion or interrupt 
routine. 

2. It is recommended that the ICDFN function be used at the 
beginning of the main program before any I/O operations are 
initiated. 

3. If ICDFN is executed more than once, a completely new set of 
channels is created each time ICDFN is called. 

4. ICDFN requires that extra memory space be allocated to 
foreground programs (see Section 0.1.4). 


Function Results: 


i = 0 Normal return. 

=1 An attempt was made to allocate fewer channels 

than already exist. 

= 2 Not enough free space is available for the channel 

area. 

Example: 


IF(ICDFN (24) .NE.0) STOP 'NOT ENOUGH MEMORY' 
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ICHCPY 


0.3.15 ICHCPY (F/B only) 

The ICHCPY function opens a channel for input, logically connecting it 
to a file which is currently open by another job for either input or 
output. This function may be used by either the foreground or the 
background. An ICHCPY must be done before the first read or write for 
the given channel. 


Form: i = ICHCPY (chan,ochan) 


where: chan 

ochan 



Notes: 


is the channel which the job will use to read 
the data. 

is the channel number of the other job which 
is to be copied. 


1. If the other job's channel was opened via an IENTER function 
or a .ENTER programmed request to create a file, the copier's 
channel indicates a file which extends to the highest block 
that the creator of the file had written at the time the 
ICHCPY was executed. 



2 . 


A channel which is open on a sequential-access device | 

should not be copied, because buffer requests may become 
intermixed. 


3. A program can write to a file (which is being created by the 
other job) on a copied channel just as it could if it were 
the creator. When the copier's channel is closed, however, 
no directory update takes place. 


Errors: 

i = 0 Normal return. 

= i Other job does not exist or does not have the 

specified channel (ochan) open. 

= 2 Channel (chan) is already open. 
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ICMKT 


0.3.16 ICMKT (F/B only) 

The ICMKT function causes one or more scheduling requests (made by an 
ISCHED. ITIMER or MRKT routine) to be cancelled. 

Form: i = ICMKT (id .time) 

is the identification integer of the request 
to be cancelled. If id is equal to zero, all 
scheduling requests are cancelled. 

is the name of a 2-word area in which the 
monitor will return the amount of time 
remaining in the cancelled request. 

For further information on cancelling scheduling requests. see the 
assembly language .CMKT request. Section 9.4.5. 

Errors: 

i = 0 Normal return. 

= 1 id was not equal to zero and no schedule request 

with that identification could be found. 

Example: 


where: id 


time 


INTEGERM J 


CALL ICMKT(O.J) !ABORT ALL TIMER REQUESTS NOW 


END 


0-36 







System Subroutine Library 


ICSI 


0.3.17 ICSI 

The ICSI function calls the RT-11 command string interpreter in 
special mode to parse a command string and return file descriptors and 
switches to the program. In this mode, the CSI does not perform any 
handler fetches, CLOSES, ENTERS, or LOOKUPS. ICSI cannot be called 
from a completion or interrupt routine. 


Form: i = ICSI (filspc,defext,{cstring},{switch},x) 

where: filspc is the 39-word area to receive the file 

specifications. The format of this area 
(considered as a 39-element INTEGER*2 array) 
is: 


filspc(1)- output file number 1 

filspc(4) specification 

filspc(5) output file number 1 length 


filspc(6)- output file number 2 

filspc(9) specification 

filspc(10) output file number 2 length 


filspc(11)- output file number 3 

filspc(14) specification 

filspc(15) output file number 3 length 


defext 


filspc(16)- input file number 1 
filspc(19) specification 


filspc(20)- input file number 2 
filspc(23) specification 


filspc(24)- input file number 3 
filspc(27) specification 


filspc(28)- input file number 4 
filspc(31) specification 


filspc(32)- input file number 5 
filspc(35) specification 


filspc(36)- input file number 6 
filspc(39) specification 


is the table of Radix-50 default extensions 
to be assumed when a file is specified 
without an extension. 
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defext(1) 

is the 

default 

for all 

input 


file extensions. 


defext(2) 

is the 

default 

extension 

for 


output 

file number 1. 


defext(3) 

is the 

default 

extension 

for 


output 

file number 2. 


defext(4) 

is the 

default 

extension 

for 


output 

file number 3. 



cstring is the area which contains the ASCIZ command 
string to be interpreted; the string must 
end in a zero byte. If this argument is 
omitted, the system prints the prompt 
character (*) at the terminal and accepts a 
command string. 

switch is the name of an INTEGER*2 array dimensioned 
(4,n) where n represents the number of 
switches which are defined to the program. 
This argument must be present if the value 
specified for "x" is non-zero. This array 
has the following format for the nth switch 
described by the array. 


x 


switch(1,n) 
switch(2,n) 


switch(3 ,n) 
switch(4,n) 


is the 1-character ASCII name 
of the switch. 

is set by the routine to 0, if 
the switch did not occur; to 
1, if the switch occurred 
without a value; to 2, if the 
switch occurred with a value, 
is set to the file number on 
which the switch is specified, 
is set to the specified value 
if switch(2,n) is equal to 2. 


is the number of switches defined in the 
array "switch". 


Notes: 


The array 
switches. 
switches: 


switch" must be set up to contain the names of the valid 
For example, use the following to set up names for five 


INTEGER*2 SW(4,5) 

DATA SW(1,1)/ , S , /,SW(1,2)/ , M , /,SW(1,3)/ , IV 
DATA SW(1,4)/ , L , /,SW(l,5)/'E'/ 

Multiple occurrences of the same switch are supported by allocating an 
entry in the switch array for each occurrence of the switch. Each 
time the switch occurs in the switch array, the next unused entry for 
the named switch will be used. 

The arguments of ICSI must be positioned so that the USR cannot swap 
over them. ^ 

For more information on calling the Command String Interpreter, see 
the assembly language .CSISPC request. Section 9.4.8. 
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Errors: 

i = 0 Normal return. 

= l Illegal command line; no data was returned. 

=2 An illegal device specification occurred in the 

string. 

=3 An illegal switch was specified, or a given switch 

was specified more times than allowed for in the 
switch array. 

Example: 

The following example causes the program to loop until a valid command 
is typed at the console terminal. 

INTEGER*2 SPEC(39) 

REAL*4 EXT(2) 

DATA EXT/6RDATDAT,6RDATDAT/ 


TYPE 99 

FORMAT (' ENTER VALID CSI STRING WITH NO SWITCHES') 
IF(ICSI(SPEC,EXT,,,0).NE.O) GOTO 10 


10 

99 


ICSTAT 


0.3.18 ICSTAT (F/B only) 

The ICSTAT function furnishes the user with information about a 
channel. It is supported only in the F/B environment; no information 
is returned when operating under the Single-Job Monitor. 


Form: i = ICSTAT (chan,addr) 

where: chan is the channel whose status is desired. 

addr is a 6-word area to receive the status 

information. The area, as a 6-element 
INTEGER*2 array, has the following format. 


addr(l) channel status word (see 

Section 9.4.34) 

addr (2) starting block number of file 

on this channel 
addr (3) length of file 

addr (4) highest block number written 

since file was opened (see 

Section 9.4.9) 
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addr(5) unit number of device with 
which this channel is 

associated 

addr(6) Radix-50 of device name with 
which the channel is associated 

Errors: 

i = 0 
= 1 

Example: 

The following example obtains channel status information about channel 

I • 

INTEGER*2 AREA(6) 

1 = 7 

IF(ICSTAT(I,AREA).NE.O) TYPE 99,1 
99 FORMAT(IX,'CHANNEL' ,14,'IS NOT OPEN') 


Normal return. 

Channel specified is not open. 


IDELET 


0.3.19 IDELET 


The IDELET function deletes a named file from an indicated device. 
IDELET cannot be issued from a completion or interrupt routine. 

Form: i = IDELET (chan ,dblk{.count}) 


where: chan 


dblk 


count 


is the channel to be used for the delete 
operation. 

is the 4-word Radix-50 specification 
(dev:filnam.ext) for the file to be deleted. 

is used by magtape/cassette only to prevent a 
rewind before the operation. (Refer to 
Appendix H for more information concerning 
the magtape and cassette handlers.) 


NOTE 

The arguments of IDELET must be 
located so that the USR cannot swap 
over them. 
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The specified channel is left inactive when the IDELET is complete. 
IDELET requires that the handler to be used be resident (via an IFETCH 
call) at the time the IDELET is issued. If it is not, a monitor error 
occurs. 

For further information on deleting files, see the assembly language 
.DELETE request. Section 9.4.10. 

Errors: 

i = 0 Normal return. 

= i Channel specified is already open. 

= 2 File specified was not found. 

Example: 

The following example deletes a file named FTN5.DAT from SYO. 

REAL*4 FILNAM(2) 

DATA FILNAM/6RSY0FTN,6R5 DAT/ 


I=IGETC() 

IF(I.LT.O) STOP 'NO CHANNEL' 
CALL IDELET(I,FILNAM) 

CALL IFREEC(I) 


IDJFLT 


0.3.20 IDJFLT 

The IDJFLT function converts an INTEGER*4 value into a REAL*8 (DOUBLE 
PRECISION) value and stores the result. 

Form: i = IDJFLT (jsrc,dres) 

where: jsrc specifies the INTEGER*4 variable that is to 

be converted. 

dres specifies the REAL*8 (or DOUBLE PRECISION) 

variable to receive the converted value. 

Function Results: 

The function result indicates the following: 

i = -l Normal return; the result is negative. 

= o Normal return; the result is zero. 

= i Normal return; the result is positive. 
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Example: 

INTEGER*4 JJ 
REAL*8 DJ 


IF(IDJFLT(JJ,DJ) .LE.O) TYPE-99 
99 FORMAT (' VALUE IS NOT POSITIVE') 


IDSTAT 


0.3.21 IDSTAT 

The IDSTAT function is used to obtain information about a particular 
device. IDSTAT cannot be issued from a completion or interrupt 
routine. 


Form: i = IDSTAT (devnam,cblk) 


where: 


devnam 
cbl k 


is the Radix-50 device name. 

is the 4-word area used to store the status 
information. The area, as a 4-element 
INTEGER*2 array, has the following format: 

cblk(l) device status word (see Section 
9.4.12) 

cblk (2) size of handler in bytes 
cblk(3) entry point of handler 
(non-zero implies that the 
handler is in memory) 
cblk(4) size of the device (in 256-word 
blocks) for block-replaceable 
devices; zero for sequential- 
access devices 


NOTE 

The arguments of IDSTAT must be 
positioned so that the USR cannot 
swap over them. 


IDSTAT looks for the device specified by devnam and, if found, returns 
four words of status in cblk. 
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Errors: 



Normal return. 

Device not found in monitor tables. 


Example: 


The following example determines whether the line printer 
in memory. If it is not, the program stops and prints 
indicate that the handler must be loaded. 


handler 
a message 


is 

to 


REAL*4 IDNAM 
INTEGERS CBLK (4 ) 

DATA IDNAM/3RLP / 

DATA CBLK/4*0/ 

CALL IDSTAT(IDNAM,CBLK) 

IF(CBLK(3).EQ.O) STOP 'LOAD THE LP HANDLER AND RERUN' 


IENTER 


0.3.22 IENTER 

The IENTER function allocates space on the specified device and 
creates a tentative directory entry for the named file. If a file of 
the same name already exists on the specified device, it is not 
deleted until the tentative entry is made permanent by CLOSEC. The 
file is attached to the channel number specified. 

Form: i = IENTER (chan,dblk,length{ ,count}) 


where: 


chan is the integer specification for the RT-11 

channel to be associated with the file. 

dblk is the 4-word Radix-50 descriptor of the file 

to be operated upon. 

length is the integer number of blocks to be 

allocated for the file. If zero, the larger 
of either one-half the largest empty segment 
or the entire second largest empty segment is 
allocated (see Section 9.4.13). If the value 
specified for length is -1, the entire 
largest empty segment is allocated. 

count is used by magtape/cassette only to prevent a 

rewind before the operation (see Appendix H). 
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Notes: 


1 . 

IENTER cannot 
routine. 

be issued from 

a completion 

or interrupt 

2. 

IENTER requires that the appropriate device 
memory. 

handler be in 

3. 

The arguments 
does not swap 

of IENTER must be 
over them. 

positioned so 

that the USR 


For further information on creating tentative directory entries, see 
the assembly language .ENTER request, Section 9.4.13. 

Errors: 

i = n 

= -1 
= -2 


Example: 

The following example allocates a channel for file TEMP.TMP on YO. If 
no channel is available, the program prints a message and halts. 

REAL*4 DBLK(2) 

DATA DBLK/6RSY0TEM,6RP TMP/ 

ICHAN=IGETC() 

IF(ICHAN.LT.0) STOP 'NO AVAILABLE CHANNEL' 

C 

C CREATE TEMPORARY WORK FILE 
C 

IF(IENTER(ICHAN,DBLK,20).LT.0) STOP 'ENTER FAILURE' 


CALL PURGE(ICHAN) 
CALL IFREEC(ICHAN) 


Normal return; number of blocks actually 
allocated (n = 0 for nonfile-structured IENTER) . 
Channel (chan) is already in use. 

In a fixed-length request, no space greater than 
or equal to length was found. 


I FETCH 


0.3.23 IFETCH 

The IFETCH function loads a device handler into memory from the system 
device, making the device available for input/output operations. The 
handler is loaded into the free area managed by the FORTRAN system. 
Once the handler is loaded, it cannot be released and the memory in 
which it resides cannot be reclaimed. IFETCH cannot be issued from a 
completion or interrupt routine. 
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Form: i = IFETCH (devnam) 

where: devnam is the 1-word Radix-50 name of the device for 

which the handler is desired. This argument 
can be the first word of an ICSI input or 
output file specification. This argument 
must be positioned so that the USR cannot 
swap over it. 

For further information on loading device handlers into memory, see 
the assembly language .FETCH request. Section 9.4.15. 

Errors: 

i = 0 
= 1 
= 2 
= 3 


Example: 

The following example requests the DX1 handler to be loaded into 
memory; execution stops if the handler cannot be loaded. 

REAL*4 IDNAM 
DATA IDNAM/3RDX1/ 


Normal return. 

Device name specified does not exist. 

Not enough room exists to load the handler. 

No handler for the specified device exists on the 
system device. 


IF (IFETCH(IDNAM).NE.0) STOP 'FATAL ERROR FETCHING HANDLER* 


IFREEC 


0.3.24 IFREEC 

The IFREEC function returns a specified RT-11 channel to the available 
pool of channels. Before IFREEC is called, the specified channel must 
be closed or deactivated with a CLOSEC (see Section 0.3.3) or a PURGE 
(see Section 0.3.70) call. IFREEC cannot be called from a completion 
or interrupt routine. IFREEC calls must be issued only for channels 
that have been successfully allocated by IGETC calls; otherwise, 
unpredictable results will occur. 

Form: i = IFREEC (chan) 

where: chan is the integer number of the channel to be 

freed. 
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Errors: 


i = 0 
= 1 


Normal return. 

Specified channel is not currently allocated. 


Example: 


See the example under IGETC, (Section 0.3.25). 


IGETC 


0.3.25 IGETC 

The IGETC function allocates an RT-11 channel (in the range 0-17 
octal) and marks it in use for the FORTRAN I/O system. IGETC cannot 
be issued from a completion or interrupt routine. 

Form: i = IGETC() 

Function Results: 

i = “1 No channels are available. 

= n Channel n has been allocated. 


Example: 


ICHAN=IGETC() 


!ALLOCATE CHANNEL 


IF(ICHAN.LT.0) STOP 'CANNOT ALLOCATE CHANNEL' 


CALL IFREEC(ICHAN) 


!FREE IT WHEN THROUGH 


END 
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IJCVT 


0.3.26 IJCVT 

The IJCVT function converts an INTEGERM value to INTEGERM format. 
If ires is not specified, the result returned is the INTEGERM value 
of jsrc. If ires is specified, the result is stored there. 


Form: i = IJCVT (jsrc { ,ires }) 


where: jsrc specifies the INTEGERM variable or array 

element whose value is to be converted. 

ires specifies the INTEGERM entity to receive the 

conversion result. 

Function results if ires is specified: 



Example: 


An overflow occurred during conversion. 
Normal return; the result is negative. 


Normal return; the 
Normal return; the 


result is zero, 
result is positive. 


INTEGERM JVAL 
INTEGERM IVAL 


IF(IJCVT(JVAL,IVAL).EQ.-2) TYPE 99 
99 FORMAT(' NUMBER TOO LARGE IN IJCVT CONVERSION') 


ILUN 


0.3.27 ILUN 

The ILUN function returns the RT-11 channel number with which a 
FORTRAN logical unit is associated. 
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Form: i = ILUN (lun) 


where: lun is an integer expression whose value is a 

FORTRAN logical unit number in the range 
1-99. 


Function Results: 



Logical unit is not open. 

Logical unit is opened to console terminal. 
RT-11 channel number n is associated with lun. 


Example: 

PRINT 99 

99 FORMAT(' PRINT DEFAULTS TO LOGICAL UNIT 6, WHICH FURTHER DEFAULTS TO LP:') 
LUNRT=ILUN(6) !WHICH RT-11 CHANNEL IS RECEIVING I/O? 


INDEX 


0.3.28 INDEX 

The INDEX subroutine searches a string for the occurrence of another 
string and returns the character position of the first occurrence of 
that string. 

Form: CALL INDEX (a,pattrn , {i},m) 

or 


m = INDEX (a,pattrn{,i}) 

where: a is the array containing the string to be 

searched. 

pattrn is the string being sought. 

i is the integer starting character position of 

the search in a. If i is omitted, a is 
searched beginning at the first character 
position. 

m is the integer result of the search; m 

equals the starting character position of 
pattrn in a, if found; otherwise it is zero. 

Errors: 

None. 
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Example: 

The following example searches the array STRING for the first 
occurrence of strings EFG and XYZ and searches the string ABCABCABC 
for the occurrence of string ABC after position 5. 


CALL SCOPY('ABCDEFGHI',STRING) 
CALL INDEX(STRING,'EFG',,M) 

CALL INDEX(STRING,'XYZ',,N) 

CALL INDEX('ABCABCABC','ABC',5,L) 


UNITIALIZE STRING 
! M=5 
! N=0 
! L=7 


INSERT 


0.3.29 INSERT 

The INSERT subroutine replaces a portion of one string with another 
string. 

Form: CALL INSERT (in ,out,i{ ,m}) 


where: 

in 

is the array 
inserted. 

containing 

the 

string 

being 


out 

is the array 
modified. 

containing 

the 

string 

being 


i is the integer specifying the character 

position in "out" at which the insertion 
begins. 

m is the integer maximum number of characters 

to be inserted. 

If the maximum number of characters (m) is not specified, all 
characters to the right of the specified character position (i) in the 
string being modified are replaced by the string being inserted. The 
insert string (in) and the string being modified (out) may be in the 
same array only if the maximum number of characters (m) is specified 
and is less than or equal to the difference between the position of 
the insert (i) and the maximum string length of the array. 

Errors: 

None. 

Example: 

CALL SCOPY('ABCDEFGHIJ',S1) 

CALL SCOPY(SI,S2) 

CALL INSERT('123',SI,6,3) 

CALL INSERT('123',S2,4) 


UNITIALIZE STRING 1 
UNITIALIZE STRING 2 
!S1 = 'ABCDE123IJ' 
!S2 = 'ABC123' 
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INTSET 


0.3.30 INTSET 


The INTSET function establishes a FORTRAN subroutine as an interrupt 
service routine, assigns it a priority, and attaches it to a vector. 
INTSET requires that extra memory be allocated to foreground programs 
that use it (see Section 0.1.4). 

Form: i = INTSET (vect,pri,id,crtn) 


where: 


vect 

pri 

id 


cr tn 


Notes: 

1 . 


is the integer specifying the address of the 
interrupt vector to which the subroutine is 
to be attached. 

is the integer specifying the actual priority 
level (4-7) at which the device interrupts. 

is the identification integer to be passed as 
the single argument to the FORTRAN routine 
when an interrupt occurs. This allows a 
single crtn to be associated with several 
INTSET calls. 

is a FORTRAN subroutine to be established as 
the interrupt routine. This name should be 
specified in an EXTERNAL statement in the 
FORTRAN program that calls INTSET. The 
subroutine has one argument: 

SUBROUTINE crtn(id) 

INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate INTSET call. 


The id argument may be used to distinguish between 
interrupts from different vectors if the routine to be 
activated services multiple devices. 

When using INTSET in F/B, the SYSLIB call DEVICE must be used 
in almost all cases to prevent interrupts from interrupting 
beyond program termination. 


3. If the interrupt routine (crtn) has control for a period 


of 
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time longer than the time in which two more interrupts using 
the same vector occur, interrupt overrun is considered to 
have occurred. The error message: 


7SYSLIB- FATAL INTERRUPT OVERRUN 


is printed and the job is aborted. Tasks requiring very fast 
interrupt response may not be viable using FORTRAN as FORTRAN 
overhead lowers RT-ll's interrupt response rate. 

4. The interrupt routine (crtn) is actually run as a completion 

routine via use of the RT-11 .SYNCH request (Section 
9.3.1.4). The "pri" argument is used for the RT-11 .INTEN 

request (Section 9.3.1.2). 

5. A .PROTECT request is issued for the vector, but no attempt 
is made to report an error if the vector is already 
protected? furthermore, the vector will be taken over 
unconditionally. See Section 9.4.25 for more information. 

6. The FORTRAN interrupt service subroutine (crtn) cannot call 
the USR. 

7. INTSET cannot be called from a completion or interrupt 
routine. 

8. Interrupt enable should not be set on the associated device 
until the INTSET call has been successfully executed. 


Errors 


i = 0 Normal return. 

= 1 Invalid vector specification. 

= 2 Reserved for future use. 

=3 No space is available for the linkage setup 


Example 


EXTERNAL CLKSUB 


!SUBR TO HANDLE KWll-P CLOCK 


I=INTSET("104,6,0,CLKSUB) 
IF (I.NE.O) GOTO 100 


!ATTACH ROUTINE 
iBRANCH IF ERROR 


END 

SUBROUTINE CLKSUB(ID) 


END 
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l PEEK 


0.3.31 IPEEK 

The IPEEK function returns the contents of the word located at a 
specified absolute 16-bit memory address. This function may be used 
to examine device registers or any location in memory. 

Form: i = IPEEK (iaddr) 

where: iaddr is the integer specification of the absolute 

address to be examined. If this argument is 
not an even value, a trap will result. 

Function Result: 

The function result (i) is set to the value of the word examined. 
Example: 

ISWIT = IPEEK("177570) !GET VALUE OF CONSOLE SWITCHES 


I POKE 


0.3.32 IPOKE 

The IPOKE subroutine stores a specified 16-bit integer value into a 
specified absolute memory location. This subroutine may be used to 
store values in device registers. 

Form: CALL IPOKE (iaddr ,ivalue) 

where: iaddr is the integer specification of the absolute 

address to be modified. If this argument is 
not an even value, a trap will result. 
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ivalue is the integer value to be stored in the 
given address (iaddr). 

Errors: 

None. 

Example: 

The following example displays the value of IVAL in the console 
display register. 

CALL IPOKE ("177570/IVAL) 

To set bit 12 in the JSW without zeroing any other bits in the JSW, 
use the following procedure. 

CALL IPOKE ("44,"10000.OR.IPEEK("44)) 


IQ SET 


0.3.33 IQSET 

The IQSET function is used to make the RT-11 queue larger (i.e., add 
available elements to the queue). These elements are allocated out of 
the free space managed by the FORTRAN system. IQSET cannot be called 
from a completion or interrupt routine. 

Form: i = IQSET (qleng) 

where: qleng is the integer number of elements to be added 

to the queue. This argument must be 
positioned so that the USR does not swap over 
it. 

All RT-11 I/O transfers are done through a centralized queue 
management system. If I/O traffic is very heavy and not enough queue 
elements are available, the program issuing the I/O requests may be 
suspended until a queue element becomes available. In an F/B system, 
the other job runs while the first program waits for the element. 
When IQSET is used in a program to be run in the foreground, the FRUN 
command must be modified to allocate space for the queue elements (see 
Section 0.1.4). 

A general rule to follow is that each program should contain one more 
queue element than the total number of I/O and timer requests that 
will be active simultaneously. Timing functions such as ITWAIT and 
MRKT also cause elements to be used and must be considered when 
allocating queue elements for a program. Note that if synchronous I/O 
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is done (i.e. IREADW/IWRITW, etc.) and no timing functions are done, 
no additional queue elements need be allocated. See Section 0.2 for a 
list of SYSLIB calls that use queue elements. 

For further information on adding elements to the queue, see the 
assembly language .QSET request. Section 9.4.27. 

Function Results: 

i = 0 Normal return. 

= 1 Not enough free space is available for the number 

of queue elements to be added; no allocation was 
made. 

Example: 

IF(IQSET(5).NE.0) STOP 'NOT ENOUGH FREE SPACE FOR QUEUE ELEMENTS' 


IRAD50 


0.3.34 IRAD50 

The IRAD50 function converts a specified number of ASCII characters to 
Radix-50 and returns the number of characters converted. Conversion 
stops on the first non-Radix-50 character encountered in the input or 
when the specified number of ASCII characters have been converted. 

Form: n = IRAD50 (icnt,input,output) 


where: 

icnt 

is the number of ASCII characters to 
converted. 

be 


input 

is the 
taken. 

area 

from which input characters 

are 


output 

is the 
stored 

area 

into which Radix-50 words 

are 


Three characters of text are packed into each word of output. The 
number of output words modified is computed by the expression (in 
integer words): 

(icnt+2)/3 

Thus, if a count of 4 is specified, two words of output are written 
even if only a 1-character input string is given as an argument. 


0-54 










System Subroutine Library 


Function Results: 

The integer number of input characters actually converted (n) is 
returned as the function result. 

Example: 

REAL*8 FSPEC 

CALL IRAD50 (12,'SYOTEMP DAT',FSPEC) 



0.3.35 IRCVD/IRCVDC/IRCVDF/IRCVDW(F/B only) 

There are four forms of the receive data function; these are used in 
conjunction with the ISDAT (send data) functions ^ a low a genera 
data/message transfer system. The receive data functions issue 
receive data programmed requests (see Section 9.4.29). These 
functions require a queue element; this should be considered whe 
IQSET function (Section 0.3.33) is executed. 

IRCVD 

The IRCVD function is used to receive data and continue execution. 
The operation is queued and the issuing job continues execution, 
some point when the job must receive the transmitted message, an MVvAIT 
should be executed. This causes the job to be suspended until the 

message has been received. 


Form: i = IRCVD (buff,went) 


where: buff 


went 


is the array to be used to buffer the data 
received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVD is 
complete. 

is the maximum integer number of words that 
can be received. 


Errors: 

i = 0 Normal return. 

=1 No foreground job exists in the system. 


0-55 













System Subroutine Library 


Example: 

INTEGER*2 MSG (41) 


CALL IRCVD(MSG,40) 

CALL MWAIT 


IRCVDC 


The IRCVDC function receives data and enters an 
completion routine when the message is received, 
and program execution stays with the issuing job. 
sends a message, the completion routine specified 


assembly language 
The IRCVDC is queued 
When the other job 
is entered. 


Form: i = IRCVDC (buff.went,crtn) 


where: buff 


went 


is the array to be used to buffer the data 
received. The array must be one word larger 
than the message to be received because the 
fi^st word will contain the integer number of 
words actually transmitted when IRCVDC is 
complete. 

is the maximum integer number of words to be 
received. 


ertn is the assembly language completion routine 

to be entered. This name must be specified 
in a FORTRAN EXTERNAL statement in the 
routine that issues the IRCVDC call. 

Errors: 

i = 0 Normal return. 

=1 No foreground job exists in the system. 


IRCVDF 


function receives data and enters a FORTRAN completion 
Turvnp^' 06 S6 ^ Section 0.2.1) when the message is received. The 
wh*n DE Vh gu ®“ ed and program execution continues with the issuing job. 

specified ifenter^ 3 ^ F ° RTRAN COm P letio " r lulTne 


Form: i - IRCVDF (buff , went , area,crtn) 


where: buff 


is the array to be used to buffer the data 
received. The array must be one word larger 
than the message to be received because the 
fi^st word will contain the integer number of 
words actually transmitted when IRCVDF is 
complete. 
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went 


area 


cr tn 


is the maximum integer number of words to be 
received. 


is a 4-word area to be set aside for linkage 
information. This area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion routines when ertn 
has been entered. 

is the FORTRAN completion routine to be 
entered. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the IRCVDF call. 


Errors: 

i = 0 Normal return. 

=1 No foreground job exists in the system. 
Example: 


INTEGER*2 MSG(41),AREA(4) 
EXTERNAL RMSGRT 


' • 

CALL 


IRCVDF(MSG,40,AREA,RMSGRT) 


IRCVDW 


The IRCVDW function is used to receive data and wait. This function 

nnM? 3 -*! J^ SSa ? e K req “ est and suspends the job issuing the request 
until the other 30 b sends a message. When execution of the issuinq 
Dob resumes, the message has been received, and the first word of the 
buffer indicates the number of words which were transmitted. 


Form: i = IRCVDW (buff,went) 


where: buff 


is- the array to be used to buffer the data 
received. The array must be one word larger 
than the message to be received because the 
first word will contain the integer number of 
words actually transmitted when IRCVDW is 
complete. 


Errors: 


is the maximum integer number of words to be 
received. 


i “ 0 Normal return. 

=1 No foreground job exists in the system. 


Example: 

INTEGER*2 MSG(41) 

IF(IRCVDW(MSG,40).NE.O) STOP 'UNEXPECTED ERROR’ 
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IREAD/IREADC/IREADF/IREADW 


0.3.36 IREAD/IREADC/IREADF/IREADW 

SYSLIB provides four modes of I/O: IREAD/IWRITE, IREADC/IWRITC, 
IREADF/IWRITF, and IREADW/IWRITW. Section 0.3.52 explains the output 
operations. These functions require a queue element? this should be 
considered when the IQSET function (Section 0.3.33) is executed. 


IREAD 

The IREAD function transfers a specified number of words from the file 
associated with the indicated channel into memory. Control returns to 
the user program immediately after the IREAD function is initiated. 
No special action is taken when the transfer is completed. 

Form: i = IREAD (went,buff,blk,chan) 


where: 

went 

is the integer number of words to 

transferred. 

be 


buff 

is the array to be used as the buffer. 
array must contain at least went words. 

This 


blk 

is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 


chan 

is the integer specification for the 
channel to be used. 

RT-11 


NOTE 

The "blk" argument must be updated, 
if necessary, by the user program. 
For example, if reading two blocks at 
a time, update blk by 2. 


When the user program needs to access the data read on the specified 
channel, an IWAIT function should be issued. This ensures that the 
IREAD operation has been completed. If an error occurred during the 
transfer, the IWAIT function indicates the error. 
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Errors: 

i = n Normal return; n equals the number of words read 

(0 for nonfile-structured read, multiple of 256 
for file-structured read). For example: 

If went is a multiple of 256 and less than 
that number of words remain in the file, n is 
shortened to the number of words that remain 
in the file; e.g., if went is 512 and only 
256 words remain, i = 256. 

If went is not a multiple of 256 and more 

than went words remain in the file, n is 

rounded up to the next block; e.g., if went 
is 312 and more than 312 words remain, i = 
512, but only 312 are read. 

If went is not a multiple of 256 and less 

than went words remain in the file, n equals 

a multiple of 256 that is the actual number 
of words being read. 

* -1 Attempt to read past end-of-file; no words remain 

in the file. 

= -2 Hardware error occurred on channel. 

= -3 Specified channel is not open. 

Example: 

INTEGER*2 BUFFER(256),RCODE,BLK 


RCODE = IREAD(256,BUFFER,BLK,ICHAN) 
IF(RCODE+1) 1010,1000,10 
C IF NO ERROR, START HERE 
10 


IF(IWAIT(ICHAN).NE.0) GOTO 1010 


1000 CONTINUE 

C END OF FILE PROCESSING 


CALL EXIT 

1010 STOP 'FATAL READ' 
END 


!NORMAL END OF PROGRAM 
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IREADC 


The IREADC function transfers a specified number of words from the 
indicated channel into memory. Control returns to the user program 
immediately after the IREADC function is initiated. When the 
operation is complete, the specified assembly language routine (crtn) 
is entered as an asynchronous completion routine. 

Form: i = IREADC (went,buff,blk,chan ,crtn) 


where: went 


buff 

blk 


chan 


crtn 


Errors: 


is the integer number of words to be 

transferred. 

is the array to be used as the buffer. This 
array must contain at least went words. 

is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 

is the integer specification for the RT-11 
channel to be used. 

is the assembly language routine to be 
activated when the transfer is complete. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the IREADC call. 


See Errors under IREAD. 


Example: 

INTEGERS IBUF (256) ,RCODE, IBLK 
EXTERNAL RDCMP 


RCODE = IREADC(256,IBUF ,IBLK,ICHAN,RDCMP) 


IREADF 

The IREADF function transfers a specified number of words from the 
indicated channel into memory. Control returns to the user program 
immediately after the IREADF function is initiated. When the 
operation is complete, the specified FORTRAN subprogram (crtn) is 
entered as an asynchronous completion routine (see Section 0.2.1). 

Form: i = IREADF (went,buff,blk,chan,area,crtn) 


where: 

went 

is the integer 
transferred. 

number of words to 

be 


buff 

is the array to be 

used as the buffer. 

This 



array must contain 

at least went words. 
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51 k is the integer block number of the file to be 

used. The user program normally updates blk 
before it is used again. 

chan is the integer specification for the RT-11 

channel to be used. 

area is a 4-word area to be set aside for linkage 

information; this area must not be modified 
by the FORTRAN program or swapped over by the 
USR. This area may be reclaimed by other 
FORTRAN completion functions when crtn has 
been activated. 

crtn is the FORTRAN routine to be activated on 

completion of the transfer. This name must 
be specified in an EXTERNAL statement in the 
routine that issues the IREADF call. The 
subroutine has two arguments: 

SUBROUTINE crtn ( iargl,iarg2) 

iargl is the channel status word (see 

Section 9.4.34) for the operation 
just completed. If bit 0 is set, a 
hardware error occurred during the 
transfer. 

iarg2 is the octal channel number used 

for the operation just completed. 

Errors: 

See Errors under IREAD. 

Example: 

INTEGER*2 DBLK(4),BUFFER(256), BLKNO 

DATA DBLK/3RDX0,3RINP,3RUT ,3RDAT/,BLKNO/0/ 

EXTERNAL RCMPLT 


ICHAN=IGETC() 

IF(ICHAN.LT.0) STOP 'NO CHANNEL AVAILABLE 
IF(IFETCH(DBLK).NE.0) STOP 'BAD FETCH' 

IF(LOOKUP(ICHAN,DBLK).LT.O) STOP 'BAD LOOKUP' 


20 IF(IREADF(256,BUFFER,BLKNO,ICHAN,DBLK,RCMPLT).LT.O) GOTO 100 

C PERFORM OVERLAP PROCESSING 


C 


SYNCHRONIZER 
CALL IWAIT(ICHAN) 
BLKNO=BLKNO+l 
GOTO 20 


IWAIT FOR COMPLETION ROUTINE TO RUN 
'UPDATE BLOCK NUMBER 
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C END OF FILE PROCESSING 
100 CALL CLOSEC(ICHAN) 

CALL IFREEC(ICHAN) 


CALL EXIT 
END 

SUBROUTINE RCMPLT(I,J) 

C THIS IS THE COMPLETION ROUTINE 


RETURN 

END 


IREADW 


The IREADW function 
indicated channel 
when the transfer is 


transfers a specified number of words from the 
into memory. Control returns to the user program 
complete or when an error is detected. 


Form: i = IREADW (went,buff,blk,chan) 


where: went 


is the integer number of words 
transferred. 


to be 


buff 

blk 


chan 


Errors: 

See Errors under IREAD. 


is the array to be used as the buffer. This 
array must contain at least went words. 

is the integer block number of the file to be 
read. The user program normally updates blk 
before it is used again. 

is the integer specification for the RT-11 
channel to be used. 


Example: 

INTEGER*2 IBUF(1024) 


C 

C 

C 


ICODE=IREADW(1024,IBUF,IBLK,ICHAN) 

G0T0 100 !END OF FILE PROCESSING AT 100 

IF(ICODE.LT.-1) GOTO 200 !ERROR PROCESSING AT 200 


MODIFY BLOCKS 


C 

C WRITE THEM OUT 
C 

ICODE=IWRITW(1024,IBUF,IBLK,ICHAN) 
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IRENAM 


0.3.37 IRENAM 


The IRENAM function causes an immediate change of the name of a 
specified file. An error occurs if the channel specified is already 
open. 

Form: i = IRENAM (chan,dblk) 

where: chan is the integer specification for the RT-11 

channel to be used for the operation. 


dblk 


is the 8-word area specifying the name of the 
existing file and the new name to be 
assigned. If considered as an 8-element 
INTEGER*2 array, dblk has the form: 


dblk(1)-dblk(4) 

specify the 

Radix-50 

file 


descriptor 
file name. 

for 

the 

old 

dblk(5)-dblk(8) 

specify the 

Radix-50 

file 


descriptor 
file name. 

for 

the 

new 


NOTE 

The arguments of IRENAM must be 
positioned so that the USR does not 
swap over them. 


If a file with the same name as the new file name specified already 
exists on the indicated device, it is deleted. The specified channel 
is left closed when the IRENAM is complete. IRENAM requires that the 
handler to be used be resident at the time the IRENAM is issued. If 
it is not, a monitor error occurs. The device names specified in the 
file descriptors must be the same. 


For more information on renaming files, see the assembly language 
.RENAME request. Section 9.4.32. 

Errors: 

i = 0 Normal return. 

= 1 Specified channel is already open. 

= 2 Specified file was not found. 
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Example: 


REAL*8 NAME(2) 

DATA NAME/12RDK0FTN2 DAT,12RDK0FTN2 OLD/ 


ICHAN=IGETC() 

IF(ICHAN.LT.0) STOP 'NO CHANNEL' 

CALL IRENAM(ICHAN,NAME) !PRESERVE OLD DATA FILE 

CALL IFREEC(ICHAN) 


IREOPN 


0.3.38 IREOPN 

The IREOPN function reassociates a specified channel with a file on 
which an ISAVES was performed (see Section 0.3.39). The ISAVES/IREOPN 
combination is useful when a large number of files must be operated on 
at one time. As many files as are needed can be opened with LOOKUP 
and their status preserved with ISAVES. When data is required from a 
file, an IREOPN enables the program to read from the file. The IREOPN 
need not be done on the same channel as the original LOOKUP and 
ISAVES. 

Form: i = IREOPN (chan,cblk) 


where: chan 


cblk 


is the integer specification for the RT-11 
channel to be associated with the reopened 
file. This channel must be initially in an 
inactive state. 


is the 5-word block where the channel status 
information was stored by a previous ISAVES. 
This block, considered as a 5-element 
INTEGER*2 array, has the following format: 


cblk(1) 
cblk(2) 

cblk(3) 

cblk(4) 
cblk(5) 


Channel status word (see 
Section 9.4.33) . 

Starting block number of the 
file; zero for nonfile- 

structured devices. 

Length of file (in 256-word 
blocks). 

(Reserved for future use.) 

Two information bytes. Even 
byte: I/O count of the number 

of requests made on this 
channel. Odd byte: unit 

number of the device associated 
with the channel. 
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Errors: 

i = 0 Normal return. 

= 1 Specified channel is already in use. 

Example: 

INTEGER*2 SAVES(5,10) 

DATA ISVPTR/1/ 


CALL ISAVES(ICHAN,SAVES(1,ISVPTR)) 


CALL IREOPN (ICHAN,SAVES(1,ISVPTR)) 


ISAVES 


0.3.39 ISAVES 

The ISAVES function stores five words of channel status information 
into a user-specified array. These words contain all the information 
that RT-11 requires to completely define a file. When an ISAVES is 
finished, the data words are placed in memory and the specified 
channel is closed and is again available for use. When the saved 
channel data is required, the IREOPN function (Section 0.3.38) is 
used. 


ISAVES can be used only if a file was opened with a LOOKUP call (see 
Section 0.3.66). If IENTER was used, ISAVES is illegal and returns an 
error. Note that ISAVES is not legal on magtape or cassette files. 

Form: i = ISAVES (chan,cblk) 

where: chan is the integer specification for the RT-11 

channel whose status is to be saved. 

cblk is a 5-word block into which the channel 

status information describing the open file 
is stored. See Section 0.3.38 for the format 
of this block. 

The ISAVES/IREOPN combination is very useful, but care must be 
observed when using it. In particular, the following cases should be 
avoided. 

1. If an ISAVES is performed on a file and the same file is then 
deleted before it is reopened, the space occupied by the file 
becomes available as an empty space which could then be used 
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by the IENTER function. If this sequence occurs, the 
contents of the file whose status was supposedly saved will 
change. 

2. Although the handler for the required peripheral need not be 
in memory for execution of an IREOPN, a fatal error is 
generated if the handler is not in memory when an IREAD or 
IWRITE is executed. 

Errors: 

i = 0 Normal return. 

” ^ The specified channel is not currently associated 

with any file. 

= 2 Th e file was opened with an IENTER call; an 

ISAVES is illegal. 

Example: 


INTEGER*2 BLK(5) 


IF(ISAVES(ICHAN,BLK).NE.0) STOP 'ISAVES ERROR' 


ISCHED 


0.3.40 ISCHED (F/B Only) 


The ISCHED function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine at a specified time-of-day. 


Form; i = ISCHED 
where: hrs 

min 


(hrs,min,sec,tick,area,id,crtn) 

is the integer number of hours, 
is the integer number of minutes. 


is the integer number of seconds. 

is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks) . 


is a 4-word-area which must be provided for 
linkage information; this area must never be 
modified by the FORTRAN program, and the USR 
must not swap over it. This area may be 
reclaimed by other FORTRAN completion 
functions when crtn has been activated. 
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id is the identification integer to be passed to 

the routine being scheduled. 

crtn is the name of the FORTRAN subroutine to be 

entered at the time-of-day specified. This 
name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISCHED call. The subroutine has one 
argument, e.g., 

SUBROUTINE crtn(id) 

INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate ISCHED call. 


Notes: 

1. The scheduling request made by this function may be cancelled 
at a later time by an ICMKT function call. 

2. If the system is busy, the actual time-of-day that the 

completion routine is run may be greater than the requested 
time-of-day. 

3. A FORTRAN subroutine may periodically reschedule itself by 

issuing its own ISCHED or ITIMER calls from within the 

routine. 

4. ISCHED requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

Errors: 

i = 0 Normal return. 

=1 No queue elements available; unable to schedule 
request. 

Example: 

INTEGER*2 LINK(4) !LINKAGE AREA 

EXTERNAL NOON !NAME OF ROUTINE TO RUN 


I=ISCHED(12,0,0,0, LINK, 0, NOON) !RUN SUBR NOON AT 12 PM 

. (rest of main program) 

END 

SUBROUTINE NOON(ID) 

C 

C THIS ROUTINE WILL TERMINATE EXECUTION AT LUNCHTIME, 

C IF THE JOB HAS NOT COMPLETED BY THAT TIME. 

C 

STOP 'ABORT JOB — LUNCHTIME' 

END 
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IS D AT/1SDATC /I SD AT F/l S DAT W 


0.3.41 ISDAT/1SDATC/1SDATF/1SDATW (F/B only) 

These functions are used with the IRCVD/IRCVDC/IRCVDF, and IRCVDW 
calls to allow message transfers under the F/B Monitor. Note that the 
buffer containing the message should not be modified or reused until 
the message has been received by the other job. These functions 
require a queue element; this should be considered when the IQSET 
function (Section 0.3.33) is executed. 


ISDAT 

The ISDAT function transfers a specified number of words from one job 
to the other. Control returns to the user program immediately after 
the transfer is queued. This call is used with the MWAIT routine (see 
Section 0.3.68). 

Form: i = ISDAT (buff,went) 


buff 

is the array 
transferred. 

containing 

the 

data 

to 

be 

went 

is the integer 
transferred. 

number of 

data 

words 

to 

be 


Errors: 

i = 0 Normal return. 

=1 No foreground job currently exists in the system. 
Example: 

INTEGER*2 MSG(40) 

CALL ISDAT(MSG,40) 


CALL MWAIT 

C PUT NEW MESSAGE IN BUFFER 
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ISDATC 

The ISDATC function transfers a specified number of words from one job 
to another. Control returns to the user program immediately after the 
transfer is queued. When the other job accepts the message through a 
receive data request, the specified assembly language routine (crtn) 
is activated as an asynchronous completion routine. 

Form: i = ISDATC (buff,went,crtn) 


where: 

buff 

is the array 
transferred. 

containing 

the 

data 

to 

be 


went 

is the integer 
transferred. 

number of 

data 

words 

to 

be 


crtn is the name of an assembly language routine 

to be activated on completion of the 
transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the ISDATC call. 

Errors: 

i = 0 Normal return. 

=1 No foreground job currently exists in the system. 

Example: 

INTEGER*2 MSG (40) 

EXTERNAL RTN 


CALL ISDATC(MSG,40,RTN) 


ISDATF 

The ISDATF function transfers a specified number of words from one job 
to the other. Control -returns to the user program immediately after 
the transfer is queued and execution continues. When the other job 
accepts the message through a receive data request, the specified 
FORTRAN subprogram (crtn) is activated as an asynchronous completion 
routine (see Section 0.2.1). 

Form: i = ISDATF (buff,went,area,crtn) 


where: 

buff 

is the array 
transferred. 

containing 

the 

data 

to 

be 


went 

is the integer 
transferred. 

number of 

data 

words 

to 

be 


area is a 4-word area to be set aside for linkage 

information; this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has been activated. 
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crtn is the name of a FORTRAN routine to be 

activated on completion of the transfer. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISDATF call. 


Errors: 

i = 0 Normal return. 

=1 No foreground job currently exists in the system. 

Example: 

INTEGER*2 MSG (40) ,SPOT (4) 

EXTERNAL RTN 

CALL ISDATF(MSG,40,SPOT,RTN) 

ISDATW 

The ISDATW function transfers a specified number of words from one job 
to the other. Control returns to the user program when the other job 
has accepted the data through a receive data request. 

Form: i = ISDATW (buff,went) 


buff 

is the array 
transferred. 

containing 

the 

data 

to 

be 

went 

is the integer 
transferred. 

number of 

data 

words 

to 

be 


Errors: 

i = 0 Normal return. 

=1 No foreground job currently exists in the system. 
Example: 

INTEGERS MSG (40) 


IF 


(ISDATW(MSG,40).NE.O) STOP 'FOREGROUND JOB NOT RUNNING' 
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ISLEEP 


0.3.42 ISLEEP (F/B Only) 

The ISLEEP function suspends the main program execution of a job for a 
specified amount of time. The specified time is the sum of hours, 
minutes, seconds, and ticks specified in the ISLEEP call. All 
completion routines continue to execute. 

Form: i = ISLEEP (hrs,min,sec,tick) 


where: hrs 

is 

the 

integer 

number 

of 

hours. 

min 

is 

the 

integer 

number 

of 

minutes. 

sec 

is 

the 

integer 

number 

of 

seconds. 

tick 

is 

the 

integer 

number 

of 

ticks (1/60 of a 


second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks). 


Notes: 

1. ISLEEP requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2. If the system is busy, the time that execution is suspended 
may be greater than that specified. 

Errors: 

i = 0 Normal return. 

= 1 No queue element available. 

Example: 


CALL IQSET(2) 


CALL ISLEEP(0,0,0,4) IGIVE BACKGROUND JOB SOME TIME 
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ISPFN/ISPFNC/ISPFNF/ISPFNW 


0.3.43 ISPFN/ISPFNC/ISPFNF/ISPFNW 

These functions are used in conjunction with special functions to 
various handlers (cassette, diskette, and magtape). They provide a 
means of doing device-dependent functions, such as rewind and 
backspace, to those devices. If ISPFN function calls are made to any 
other devices, the function call is ignored. 

To use these functions, the handler must be in memory and a channel 
associated with a file via a non-file structured LOOKUP call. These 
functions require a queue element; this should be considered when the 
IQSET function (Section 0.3.33) is executed. Refer to Appendix H for 
details of CT, DX, and MT handlers. 


ISPFN 

The ISPFN function queues the specified operation and immediately 
returns control to the user program. The IWAIT function may be used 
to ensure completion of the operation. 

Form: i = ISPFN (code ,chan{,went,buff,blk }) 


where: code 


chan 


went 


buff 


is the integer numeric code of the function 
to be performed (see Table 0-2). 

is the integer specification for the RT-11 
channel to be used for the operation. 

is the inteqer number of data words in the 
operation. 1 

is the array to be used as the data 
buffer. 1 


blk is the integer block number of the file to be 

operated upon. 1 


^hese optional parameters are required only when doing a write 
with extended record gap to MT or a read or write to DX. If specified 
and not required, these arguments must be 0. 


January 1976 
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Table 0-2 

Special Function Codes (Octal) 


Function 

MT 

CT 

DX 

Read absolute 



377 

Write absolute 



376 

Write absolute with 




deleted data 



375 

Backspace to last file 


377 


Backspace to last block 


376 


Forward to next file 


375 


Forward to next block 


374 


Rewind to load point 

373 

373 


Write file gap 


372 


Write EOF 

377 



Forward 1 record 

376 



Backspace 1 record 

375 



Write with extended 




record gap 

374 



Offline 

372 




Errors: 

i = 0 Normal return. 

= 1 Attempt to read or write past end-^f-file. 
= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 

Example: 


CALL ISPFN ("373 ,ICHAN) !REWIND 


ISPFNC 


The ISPFNC function queues the specified operation and immediately 
returns control to the user program. When the operation is complete, 
the specified assembly language routine (crtn) is entered as an 
asynchronous completion routine. 

Form: i = ISPFNC (code ,chan ,went,buff,blk,crtn) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2). 

chan is the integer specification for the RT-11 

channel to be used for the operation. 


went is the integer number of data words in the 

operation. This argument must be 0 if not 
required. 


buff is the array to be used as the data buffer. 

This argument must be 0 if not required. 

blk is the integer block number of the file to be 

operated upon. This argument must be 0 if 
not required. 
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is the name of an assembly language routine 
to be activated on completion of the 
operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the ISPFNC call. 


Errors: 

i = 0 Normal return. 

= 1 Attempt to read or write past end-of-file. 
= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 


ISPFNF 

The ISPFNF function queues the specified operation and immediately 
returns control to the user program. When the operation is complete , 
the specified FORTRAN subprogram (crtn) is entered as an asynchronous 
completion routine. 


Form: i = ISPFNF (code,chan,wcnt,buff,blk,area,crtn) 


where: code 

chan 

went 

buff 

blk 

area 


is the integer numeric code of the function 
to be performed (see Table 0-2). 

is the integer specification for the RT-11 
channel to be used for the operation. 

is the integer number of data words in the 
operation. This argument must be 0 if not 
required. 

is the array to be used as the data buffer. 
This argument must be 0 if not required. 

is the integer block number of the file to be 
operated upon. This argument must be 0 if 
not required. 

is a 4-word area to be set aside for linkage 
information? this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has been activated. 


crtn is the name of a FORTRAN routine to be 

activated on completion of the operation. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the ISPFNF call. The subroutine has two 
arguments: 

SUBROUTINE crtn ( iargl,iarg2) 

iargl is the channel status word (see 

Section 9.4.34) for the operation 
just completed. If bit 0 is set, a 
hardware error occurred during the 
transfer. 

iarg2 is the channel number used for the 

operation just completed. 
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Errors: 

i = 0 Normal return. 

= 1 Attempt to read or write past end-of-file. 
= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 


Example: 

REALM MTNAME (2 ) ,AREA (2 ) 
DATA MTNAME/3RMT0, 0./ 
EXTERNAL DONSUB 


I=IGETC() 

CALL IFETCH(MTNAME) 

CALL LOOKUP(I,MTNAME) 
IERR=ISPFNF("373,1,0,0,0 


•ALLOCATE CHANNEL 
•FETCH MT HANDLER 

!NON-FILE STRUCTURED LOOKUP ON MTO 
AREA,DONSUB) !REWIND MAGTAPE 


END 

SUBROUTINE DONSUB 
C 

C RUNS WHEN MTO HAS BEEN REWOUND 
C 


END 


ISPFNW 


The ISPFNW function queues the specified operation and returns control 
to the user program when the operation is complete. 


Form: i = ISPFNW (code ,chan{,wcnt,buff,blk}) 

where: code is the integer numeric code of the function 

to be performed (see Table 0-2). 


chan is the integer specification for the RT-11 

channel to be used for the operation. 

went is the integer number of data words in the 

operation. 1 

buff is the array to be used as the data 

buffer. 1 

blk is the integer block number of the file to be 

operated upon. 1 


x These optional parameters are required only when doing a write 
with extended record gap to MT or a read or write to DX. If specified 
and not required, these arguments must be 0. 
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Errors: 

i = 0 Normal return. 

= 1 Attempt to read or write past end-of-file. 
= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 

Example: 



INTEGER*2 BUF(65) ,TRACK,SECTOR,DBLK(4) 
DATA DBLK/3RDX0,0,0,0/ 


ICHAN=IGETC() 

IF(ICHAN.LT.0) STOP 'NO CHANNEL AVAILABLE' 

IF(LOOKUP (ICHAN,DBLK) .LT.0) STOP 'BAD LOOKUP* 


C 

C 

C 

C 

C 


READ AN ABSOLUTE TRACK AND SECTOR FROM THE FLOPPY 


ICODE=ISPFNW("377,ICHAN,TRACK,BUF,SECTOR) 

BUF(l) IS THE DELETED DATA FLAG 
BUF(2-65) IS THE DATA 


I SPY 



0.3.44 ISPY 


The ISPY function returns the integer value < 
offset from the RT-11 resident monitor, 
information on fixed offset references.) 

Form: i = ISPY (ioff) 

where: ioff is the offset (from 

examined. 


f the word at a specified 
(See Section 9.2.6 for 

the base of RMON) to be 


Function Result: 

The function result (i) is set to the value of the word examined. 
Example: 

C 

C BRANCH TO 200 IF RUNNING UNDER F/B MONITOR 
C 

IF(ISPY("300) .AND.1) GOTO 200 
C 

C WORD AT OCTAL 300 FROM RMON IS 
C THE CONFIGURATION WORD. 
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ITIMER 

0.3.45 ITIMER (F/B Only) 

The ITIMER function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine after a specified time interval 
has elapsed. 

Form: i = ITIMER (hrs,min,sec,tick,area,id,crtn) 


where: hrs 

is the integer number of hours. 

min 

is the integer number of minutes 

sec 

is the integer number of seconds. 

tick 

is the integer number of ticks (1/60 of a 
second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks). 

area 

is a 4-word area which must be provided for 
linkage information; this area must never be 
modified by the FORTRAN program, and the USR 
must never swap over it. This area may be 
reclaimed by other FORTRAN completion 
functions when crtn has been activated. 

id 

is the identification integer to be passed to 
the routine being scheduled. 

cr tn 

is the name of the FORTRAN subroutine to be 
entered when the specified time interval 
elapses. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that references ITIMER. The subroutine has 
one argument, e.g., 

SUBROUTINE crtn(id) 

INTEGER id 

When the routine is entered, the value of the 
integer argument will be the value specified 
for id in the appropriate ITIMER call. 

Notes: 



1. This function may be cancelled at a later time by an ICMKT 
function call. 
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2. If the system is busy, the actual time interval at which the 
completion routine is run may be greater than the time 
interval requested. 

3. FORTRAN subroutines can periodically re-schedule themselves 
by issuing ISCHED or ITIMER calls. 

4. ITIMER requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

For more information on scheduling completion routines, see Section 
0.2.1 and the assembly language .MRKT request. Section 9.4.22. 


Errors: 

i = 0 Normal return 

=1 No queue elements available; unable to schedule 

request. 

Example: 

INTEGER*2 AREA(4) 

EXTERNAL WATCHD 


C IF THE CODE FOLLOWING ITIMER DOES NOT REACH THE ICMKT CALL 

C IN 12 MINUTES, WATCH DOG COMPLETION ROUTINE WILL BE 

C ENTERED WITH ID OF 3 
C 

CALL ITIMER(0,12,0,0,AREA,3,WATCHD) 


CALL ICMKT(3,AREA) 


END 

SUBROUTINE WATCHD(ID) 

C 

C THIS IS CALLED AFTER 12 MINUTES 


RETURN 

END 
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ITLOCK 


0.3.46 ITLOCK (F/B Only) 

The ITLOCK function is used in an F/B system to attempt to gain 
ownership of the USR. It is similiar to LOCK (Section 0.3.65) in that 
if successful, the user job returns with the USR in memory. However, 
if a job attempts to LOCK the USR while the other job is using it, the 
requesting job is suspended until the USR is free. With ITLOCK, if 
the USR is not available, control returns immediately and the lock 
failure is indicated. ITLOCK cannot be called from a completion or 
interrupt routine. 

Form: i = ITLOCK() 

For further information on gaining ownership of the USR, see the 
assembly language .TLOCK request. Section 9.4.41. 

Errors: 

i = 0 Normal return. 

= 1 USR is already in use by another job. 

Example: 

IF(ITLOCK().NE.0) GOTO 100 iGOTO 100 IF USR BUSY 


ITTINR 


0.3.47 ITTINR 

The ITTINR function transfers a character from the console terminal to 
the user program. If no characters are available, return is made with 
an error flag set. 

Form: i = ITTINR() 


0-79 






System Subroutine Library 


If the function result (i) is less than zero when execution of the 
ITTINR function is complete, it indicates that no character was 
available; the user has not yet typed a valid line. Under the F/B 
Monitor, ITTINR does not return a result of less than zero unless bit 
6 of the Job Status Word was on when the request was issued (see 
below). 

There are two modes of doing console terminal input. The mode is 
governed by bit 12 of the Job Status Word (JSW). The JSW is at octal 
location 44. If bit 12 equals 0, normal I/O is performed. In this 
mode, the following conditions apply: 

1. The monitor echoes all characters typed; lower case 
characters are converted to upper case unless JSW bit 14 is 
set, in which case lower case characters are not translated. 

2. CTRL U (~U) AND RUBOUT perform line deletion and character 
deletion, respectively. 

3. A carriage return, line feed, CTRL Z, or CTRL C must be 
struck before characters on the current line are available to 
the program. When one of these is typed, characters on the 
line typed are passed one-by-one to the user program. Both 
carriage return and line feed are passed to the program. 

4. ALTMODEs (octal codes 175 and 176) are converted to ESCAPES 
(octal 33). 

If bit 12 equals 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL C 
and CTRL 0. 

2. CTRL U and RUBOUT do not perform special functions. 

3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters desired. 
However, CTRL C and CTRL 0 are acted on by the monitor in the usual 
way. Bits 12 and 14 in the JSW must be set by the user program if 
special console mode or lower case characters are desired (see the 
example under Section 0.3.32). These bits are cleared when control 
returns to RT-11. 


NOTE 

To set and/or clear bits in the JSW, do 
an IPEEK and then an IPOKE. In special 
terminal mode (JSW bit 12 set), normal 
FORTRAN formatted I/O from the console 
is undefined. 


In the F/B Monitor, CTRL F and CTRL B are not affected by the setting 
of bit 12. The monitor always acts on these characters if the SET TTY 
FB command was issued. 
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Under the F/B Monitor, if a terminal input request is made and no 
character is available, job execution is suspended until a character 
is ready. If a program really requires execution to continue and 
ITTINR to return a result of less than zero, it must turn on bit 6 of 
the JSW before the ITTINR. Bit 6 is cleared when a program 
terminates. 

Function Results: 


i >0 
<0 


Normal return; character read. 

Error return; no character available. 


Example: 

ICHAR=ITTINR() !READ A CHARACTER FROM THE CONSOLE 

IF(ICHAR.LT.0) GOTO 100 iCHARACTER NOT AVAILABLE 


ITTOUR 


0.3.48 ITTOUR 

The ITTOUR function transfers a character from the user program to the 
console terminal if there is room for the character in the monitor 
buffer. If it is not currently possible to output a character, an 
error flag is returned. 

Form: i = ITTOUR (char) 

where: char is the character to be output, 

right-justified in the integer (may be 
LOGICAL*l entity if desired) . 

If the function result (i) is 1 when execution of the ITTOUR function 
is complete, it indicates that there is no room in the buffer and that 
no character was output. Under the F/B Monitor, ITTOUR normally does 
not return a result of 1. Instead, the job is blocked until room is 
available in the output buffer. If a job really requires execution to 
continue and a result of 1 to be returned, it must turn on bit 6 of 
the JSW (location 44) before issuing the request. 

The ITTINR and ITTOUR have been supplied as a help to those users who 
do not wish to suspend program execution until a console operation is 
complete. With these modes of I/O, if a no-character or no-room 
condition occurs, the user program can continue processing and try the 
operation again at a later time. 

Errors: 

i = 0 Normal return; character was output. 

= 1 Error return; ring buffer is full. 
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Example: 


DO 20 1=1,5 

10 IF(ITTOUR("007).NE.0) GOTO 10 iRING BELL 5 TIMES 

20 CONTINUE 


ITWAIT 


0.3.49 ITWAIT (F/B Only) 

The ITWAIT function suspends the main program execution of the current 
job for a specified time interval. All completion routines continue 
to execute. 

Form: i = ITWAIT (itime) 

where: itime is the 2-word internal format time interval. 


itime (1) is the 
itime (2) is the 


high-order time 
low-order time. 


Notes: 


1. ITWAIT requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2. If the system is busy, the actual time interval that 
execution is suspended may be greater than the time interval 
specified. 


Errors: 


i = 0 
= 1 


Normal return. 

No queue element available 


Example: 


INTEGER*2 TIME(2) 


CALL ITWAIT(TIME) 


•WAIT FOR TIME TIME 
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IUNTIL 


0.3.50 IUNTIL (F/B Only) 


The IUNTIL function suspends main program execution of the job until 
the time-of-day specified. All completion routines continue to run. 


Form: i = IUNTIL (hrs,min,sec,tick) 


hrs 

is 

the 

integer 

number 

of 

hours. 

min 

is 

the 

integer 

number 

of 

minutes. 

sec 

is 

the 

integer 

number 

of 

seconds. 

tick 

is 

the 

integer 

number 

of 

ticks (1/60 of a 


second on 60-cycle clocks; 1/50 of a second 
on 50-cycle clocks). 


Notes: 

1. IUNTIL requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2. If the system is busy, the actual time-of-day that the 
program resumes execution may be later than that requested. 

Errors: 

i = 0 Normal return. 

=1 No queue element available. 

Example: 

C TAKE A LUNCH BREAK 

CALL IUNTIL(13,0,0,0) !START UP AGAIN AT 1 P.M. 
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IWAIT 


0.3.51 IWAIT 

The IWAIT function suspends execution of the main program until all 
input/output operations on the specified channel are complete. This 
function is used with IREAD, IWRITE, and ISPFN calls. Completion 
routines continue to execute. 

Form: i = IWAIT (chan) 

where: chan is the integer specification for the RT-11 

channel to be used. 

For further information on suspending execution of the main program, 
see the assembly language .WAIT request. Section 9.4.46. 

Errors: 

i = 0 
= 1 
= 2 


Example: 

IF(IWAIT(ICHAN).NE.0) CALL I0ERR(4) 


Normal return. 

Channel specified is not open. 

Hardware error occurred during the previous I/O 
operation on this channel. 


IWRITC/IWRITE /IWRITF/IWRITW 


0.3.52 IWRITC/IWRITE/IWRITF/IWRITW 

These functions transfer a specified number of words from memory to 
the specified channel. The IWRITE functions require queue elements; 
this should be considered when the IQSET function (Section 0.3.33) is 
executed. 
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IWRITC 

The IWRITC function transfers a specified number of words from memory 
to the specified channel. The request is queued and control returns 
to the user program. When the transfer is complete/ the specified 
assembly language routine (crtn) is entered as an asynchronous 
completion routine. 

Form: i = IWRITC (went/buff,blk f chan,crtn) 


where: went 


buff 

blk 


chan 


crtn 


is the integer number of words to be 

transferred. 

is the array to be used as the output buffer. 

is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

is the integer specification for the RT-11 
channel to be used. 

is the name of the assembly language routine 
to be activated upon completion of the 

transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine 
that issues the IWRITC call. 


NOTE 

The "blk" argument must be updated, 
if necessary/ by the user program. 
For example, if writing two blocks at 
a time, update blk by 2. 


Errors: 

i = n Normal return; n equals the number of words 

written, rounded to a multiple of 256 (0 for 
nonfile-structured writes). 


NOTE 

If the word count returned is less than 
that requested, an implied end-of-file has 
occurred although the normal return is 
indicated. 


Attempt to write past end-of-file; no more space 
is available in the file. 

Hardware error occurred. 

Channel specified is not open. 
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Example: 

INTEGER*2 IBUF(256) 
EXTERNAL CRTN 


ICODE=IWRITC(256,IBUF,IBLK,ICHAN,CRTN) 


IWRITE 


The IWRITE function transfers a specified number of words from memory 
to the specified channel. Control returns to the user program 
immediately after the request is queued. No special action is taken 
upon completion of the operation. 

Form: i = IWRITE (went,buff,blk,chan) 


where: went 


buff 

blk 


chan 


is the integer number of words to be 
transferred. 

is the array to be used as the output buffer. 

is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

is the integer specification for the RT-11 
channel to be used. 


Errors: 


See Errors under IWRITC. 
Example: 


See the example under IREAD, Section 0.3.36. 


IWRITF 

The IWRITF function transfers a number of words from memory to the 
specified channel. The transfer request is queued and control returns 
to the user program. When the operation is complete, the specified 
FORTRAN subprogram (ertn) is entered as an asynchronous completion 
routine (see Section 0.2.1). 

Form: i = IWRITF (went,buff,blk,chan,area,crtn) 


where: 

went 

is the integer number of words 
transferred. 

to be 


buff 

is the array to be used as the output 

buffer. 


blk 

is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 


chan 

is the integer specification for the 
channel to be used. 

RT-ll 
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area is a 4-word area to be set aside for linkage 

information; this area must not be modified 
by the FORTRAN program and the USR must not 
swap over it. This area may be reclaimed by 
other FORTRAN completion functions when crtn 
has been activated. 

crtn is the name of the FORTRAN routine to be 

activated upon completion of the transfer. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
t-hc IWRITF call. The subroutine has two 
arguments: 

SUBROUTINE crtn (iargl,iarg2) 

iargl is the channel status word (see 

Section 9.4.34) for the operation 
just completed. If bit 0 is set, a 
hardware error occurred during the 
transfer. 

iarg2 is the channel number used for the 

operation just completed. 

Errors; 

See Errors under IWRITC. 

Example; 

See the example under IREADF, Section 0.3.36. 


IWRITW 


The 

to 

the 


IWRITW function transfers 
the specified channel, 
transfer is complete. 


a specified number of words from memory 
Control returns to the user program when 


Form: i = IWRITW (went,buff,blk,chan) 


where: went 


is the integer number of words 
transferred. 


to 


be 


Errors: 


buff 

blk 


chan 


is the array to be used as the output buffer. 

is the integer block number of the file to be 
written. The user program normally updates 
blk before it is used again. 

is the integer specification for the RT-11 
channel to be used. 


See Errors under IWRITC. 


Example: 


See the example under IREADW, Section 0.3.36. 


0-87 








System Subroutine Library 


JADD 


0.3.53 JADD 

The JADD function computes the sum of two INTEGERM values. 

Form: i = JADD (joprl,jopr2,jres) 

where: joprl is an INTEGER*4 variable. 

jopr2 is an INTEGERM variable. 

jres is an INTEGERM variable that receives the 

sum of joprl and jopr2. 

Function Results: 

^ = _2 An overflow occurred while computing the result. 

= -1 Normal return; the result is negative. 

= o Normal return; the result is zero. 

= i Normal return; the result is positive. 

Example: 

INTEGERM JOPl,J0P2,JRES 

IF(JADD(JOPl,J0P2,JRES).EQ.-2) GOTO 100 


JAFIX 


0.3.54 JAFIX 

The JAFIX function converts a REALM value to INTEGERM. 
Form: i = JAFIX (asrc,jres) 
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where: 

asrc 

is 

to 

a REALM variable, constant, or 
be converted to INTEGERM. 

expression 


jres 

is 

the 

an INTEGERM variable that is 
result of the conversion. 

to contain 


Function Results: 

i = -2 
= -1 
= 0 
= 1 

Example: 

INTEGERM J0P1 

C READ A LARGE INTEGER FROM THE TERMINAL 
ACCEPT 99 , A 
99 FORMAT (F15.0) 

IF(JAFIX(A,JOPl).EQ.-2) GOTO 100 


An overflow occurred while computing the result. 
Normal return; the result is negative. 

Normal return; the result is zero. 

Normal return; the result is positive. 


JCMP 


0.3.55 JCMP 

The JCMP function compares two INTEGERM values and returns an 
INTEGERM value that reflects the signed comparison result. 

Form: i = JCMP (jopr1,jopr2) 

where: joprl is the INTEGERM variable or array element 

that is the first operand in the comparison. 

jopr2 is the INTEGERM variable or array element 

that is the second operand in the comparison. 

Function Result: 


i = -1 

If 

joprl 

is 

less than jopr2 

= 0 

If 

joprl 

is 

equal to jopr2 

= 1 

Example: 

If 

joprl 

is 

greater than jopr2 


INTEGERM JOPX,JOPY 


IF(JCMP(JOPX,JOPY)) 10/20,30 
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JDFIX 


0.3.56 JDFIX 

The JDFIX function converts a REAL*8 (DOUBLE PRECISION) value to 
INTEGERM. 


Form: i = JDFIX (dsrc,jres) 


where: 

dsrc 

is a REAL*8 variable, constant, or expression 
to be converted to INTEGERM. 


jres 

is an INTEGERM variable to contain the 
conversion result. 

Function Results: 



i = -2 
= -1 
= 0 
= 1 


An overflow occurred while 
Normal return? the result 
Normal return? the result 
Normal return? the result 

computing the result, 
is negative, 
is zero, 
is positive. 


Example: 

INTEGERM JNUM 
REAL*8 DPNUM 


20 TYPE 98 

98 FORMAT(' ENTER POSITIVE INTEGER') 
ACCEPT 99,DPNUM 

99 FORMAT(F20.0) 

IF(JDFIX(DPNUM,JNUM).LT.O) GOTO 20 
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JDIV 


0.3.57 JDIV 

The JDIV function computes the quotient of two INTEGER*4 values. 

Form: i = JDIV ( joprl, jopr2,jres{,jrem}) 

where: joprl is an INTEGERM variable that is the dividend 

of the operation. 

jopr2 is an INTEGERM variable that is divisor of 

joprl. 

jres is an INTEGERM variable that receives the 

quotient of the operation (i.e., 

jres=jopr1/jopr 2). 

jrem is an INTEGERM variable that receives the 

remainder of the operation. The sign is the 
same as that for joprl. 


Function Results: 


i = 

-3 

An attempt was 

made 

to divide 

by 

zero. 

= 

-2 

(not used) 





= 

-1 

Normal return; 

the 

quotient 

is 

negative. 

= 

0 

Normal return; 

the 

quotient 

is 

zero. 

= 

1 

Normal return; 

the 

quotient 

is 

positive. 

Example: 








INTEGERM 

JNl,JN2,JQUO 






CALL JDIV(JNl,JN2,JQUO) 
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JICVT 


0.3.58 JICVT 


The JICVT function converts a specified INTEGER*2 value to INTEGERM. 
Form: i = JICVT (isrc,jres) 


Where: isrc 


is the INTEGERM quantity to be converted. 


is the INTEGERM variable or array element 
which will receive the result. 


Function Results: 

i = -1 
= 0 
= 1 


Example: 


Normal return? 
Normal return; 
Normal return? 


the result is negative, 
the result is zero, 
the result is positive. 


INTEGERM JVAL 

CALL JICVT(478,JVAL) !FORM A 32-BIT CONSTANT 


JJCVT 


0.3.59 JJCVT 


The JJCVT function interchanges words of an INTEGERM value to form an 

tmJpcpdL fori ! ,a ‘\ 4 me °f vice vers a- This is necessary when the 
INTEGER 4 variable is to be used as an argument in a timer-support 
function such as ITWAIT. When a 2-word internal format time is 
specified to a function such as ITWAIT, it must have the high-order 
time as the first word and the low-order time as the second word. 

Form: CALL JJCVT (jsrc) 
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where: jsrc 


is the INTEGER*4 variable whose contents are 
to be interchanged. 


Errors: 

None. 

Example: 

INTEGER*4 TIME 

CALL GTIM(TIME) 
CALL JJCVT(TIME) 


!GET TIME OF DAY 
! TURN IT INTO INTEGERM FORMAT 


JMOV 


0.3.60 JMOV 


The JMOV function assigns the 
another INTEGERM variable and 


value of 
returns the 


an INTEGERM variable 
sign of the value moved. 


to 


Form: i = JMOV (jsrc,jdest) 


where: jsrc 


is the INTEGERM variable whose contents 
to be moved. 


are 


jdest 


is the INTEGERM variable which is the target 
of the assignment. 


Function Result: 


The value of the function is an INTEGERM value which represents 
sign of the result as follows: 



Normal return; 
Normal return; 
Normal return; 


the result 
the result 
the result 


is negative, 
is zero, 
is positive. 


the 


Example: 

The JMOV function allows an INTEGER*4 quantity to be compared with 
zero by using it in a logical IF statement, e.g.. 


INTEGERM INTI 


IF(JMOV(INTI,INTI)) 300,100,300 !GO TO STMT 300 IF INTI IS NOT 0 
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rary 


JMUL 


0.3.61 JMUL 


The JMUL function computes the product of two INTEGER*4 values. 
Form: i = jmul (joprl,jopr2,jres) 


where 

joprl 

is an INTEGER*4 
multiplicand. 

variable that 

is 

the 


jopr 2 

is an INTEGER*4 
multiplier. 

variable that 

is 

the 


jres 

is an INTEGER*4 variable that receives 
product of the operation. 

the 


Function Results: 



An overflow occurred while 
Normal return; the product 
Normal return; the product 
Normal return; the product 


computing the 
is negative, 
is zero, 
is positive. 


result. 


Example: 


INTEGER*4 J1,J2,JRES 


C 

C 

C 


IF(JMUL(J1,J2,JRES)+1 
GOTO 100 IF OVERFLOW 
GOTO 10 IF RESULT IS 
GOTO 20 IF RESULT IS 


) 100 , 10,20 

NEGATIVE 

POSITIVE OR ZERO 
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JSUB 


0.3.62 JSUB 

The JSUB function computes the difference between two INTEGERM 
values. 

Form: i = JSUB (jopr1,jopr2,jres) 


where: 


joprl 
j°P r 2 
jres 


is an INTEGERM variable that is the minuend 
of the operation. 


is an INTEGERM variable that 
subtrahend of the operation. 


is 


the 


is an INTEGERM variable that is to receive 
the difference between ioprl and iopr2 (i.e., 
jres=jopr1-jopr2). 


Function Results: 

i = -2 
= -1 
= 0 
= 1 


An overflow occurred while computing the result, 
Normal return; the result is negative. 

the result is zero, 

the result is positive. 


Normal return; 
Normal return; 


Example: 


INTEGERM JOPl,JOP2,J3 


CALL JSUB(J0P1,J0P2/J3) 
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JTIME 


0.3.63 JTIME 

The JTIME subroutine converts the time specified to the internal 
2-word format time. 

Form: CALL JTIME (hrs,min,sec,tick,time) 


hr s 

is the 

integer number of hours. 

min 

is the 

integer number of minutes. 

sec 

is the 

integer number of seconds. 

tick 

is the 
second 
for 50- 

integer number of ticks (1/60 of a 
for 60-cycle clocks; 1/50 of a second 
-cycle clocks) . 

time 

is the 
format 
time. 

2-word area to receive the internal 
time: time(l) is the high-order 

time(2) is the low-order time. 


Errors: 

None. 

Example: 

INTEGERM J1 


C CONVERT 3 HRS, 7 MIN, 23 SECONDS TO INTEGER *4 VALUE 
CALL JTIME(3/7,23,0,Jl) 

CALL JJCVT(Jl) 
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LEN 


0.3.64 LEN 

The LEN function returns the number of characters currently in the 
string contained in a specified array. This number is computed as the 
number of characters preceding the first null byte encountered. If 
the specified array contains a null string, a value of zero is 
returned. 

Form: i = LEN (a) 

where: a specifies the array containing the string: a 

must not be a quoted-string literal. 

Errors: 

None. 

Example: 


LOGICAL*! STRNG(73) 


TYPE 99,(STRNG(I),1=1,LEN(STRNG)) 
99 FORMAT('O',132A1) 


LOCK 


0.3.65 LOCK 

The LOCK subroutine is issued to "lock" the USR in memory for a series 
of operations. The USR (User Service Routine) is the section of the 
RT-11 system which performs various file management functions. 
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If all the conditions which cause swapping are satisfied, a portion of 
the user program is written into scratch blocks and the DSR is loaded. 
Otherwise, the USR which is in memory is used, and no swapping occurs. 
The USR is not released until an UNLOCK (see Section 0.3.88) is given. 
(Note that in an F/B System, calling the CSI may also perform an 

implicit UNLOCK.) A program which has many USR requests to make can 
LOCK the USR in memory, make all the requests, and then UNLOCK the 

USR; no time is spent doing unnecessary swapping. 

In an F/B environment, a LOCK inhibits the other job from using the 
USR. Thus, the USR should be locked only as long as necessary. 

Form: CALL LOCK 

Note that the LOCK routine reduces time spent in file handling by 

eliminating the swapping of the USR. If the USR is currently 

resident, LOCK involves no I/O. After a LOCK has been executed, the 
UNLOCK routine must be executed to release the USR from memory. The 
LOCK/UNLOCK routines are complementary and must be matched. That is, 
if three LOCKS are issued, at least three UNLOCKS must be done, 
otherwise the USR will not be released. More UNLOCKS than LOCKS may 
occur without error; the extra UNLOCKS are ignored. 

Notes: 

1. It is vital that the LOCK call not come from within the area 
into which the USR will be swapped. If this should occur, 
the return from the USR request would not be to the user 
program, but to the USR itself, since the LOCK function 
causes part of the user program to be saved on disk and 
replaced in memory by the USR. Furthermore, subroutines, 
variables, and arrays in the area where the USR is swapping 
should not be referenced while the USR is LOCKed in memory. 

2. Once a LOCK has been performed, it is not advisable for the 

program to destroy the area the USR is in, even though no 

further use of the USR is required. This causes 
unpredictable results when an UNLOCK is done. 

3. LOCK cannot be called from a completion or interrupt routine. 

4. If a SET USR NO SWAP command has been issued, LOCK and UNLOCK 

will not cause the USR to swap but, in F/B, LOCK will still 

inhibit the other job from using the USR and UNLOCK will 
allow the other job access to the USR. 

5. Argument lists, such as device file name specifications, 
being passed to the USR must not be in the area into which 
the USR has just been locked. 

Errors: 

None. 
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LOOKUP 


0.3.66 LOOKUP 

The LOOKUP function associates a specified channel with a device 
and/or file for the purpose of performing I/O operations. The channel 
used is then busy until one of the following functions is executed. 

CLOSEC 

ISAVES 

PURGE 


Form: i = LOOKUP (chan,dblk{ ,count}) 


where: chan is the integer specification for the RT-11 

channel to be associated with the file. 


dblk is the 4-word area specifying the Radix-50 

file descriptor. Note that unpredictable 
results will occur if the USR swaps over this 
4-word area. 

count is an optional argument used for the magtape 

and cassette handlers (See Appendix H). 


NOTE 

The arguments of LOOKUP must be 
positioned so that the USR does not 
swap over them. 


The handler for the selected device must be in memory for a LOOKUP. 
If the first word of the file name in dblk is zero and the device is a 
file-structured device, absolute block 0 of the device is designated 
as the beginning of the "file". This technique, called a nonfile- 
structured lookup, allows I/O to any physical block on the device. If 
a file name is specified for a device which is not file-structured 
(i.e. LP:FILE.EXT) , the name is ignored. 


NOTE 

Since nonfile-structured lookups allow 
I/O to any physical block on the device, 
the user must be aware that, in this 
mode, it is possible to overwrite the 
RT-11 device directory, thus destroying 
all file information on the device. 
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Errors: 



Normal return; n equals the number of blocks in 
the file (0 for nonfile-structured lookups). 
Channel specified is already open. 

File specified was not found on the device. 


Example: 

INTEGER*2 DBLK(4) 

DATA DBLK/3RDK0,3RFTN,3R44 ,3RDAT/ 


ICHAN=IGETC() 

IF(ICHAN.LT.0) STOP 'NO CHANNEL’ 

IF(IFETCH(DBLK).NE.0) STOP 'BAD FETCH’ 

IF(LOOKUP(ICHAN,DBLK).LT.0) STOP 'BAD LOOKUP' 


CALL CLOSEC(ICHAN) 
CALL IFREEC(ICHAN) 


MRKT 


0.3.67 MRKT (F/B only) 


The MRKT function schedules an assembly language completion routine to 
be entered after a specified time interval has elapsed. 

Form: i = MRKT (id,crtn,time) 

where: id is an integer identification number to be 

passed to the routine being scheduled. 

crtn is the name of the assembly language routine 

to be entered when the time interval elapses. 
This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues 
the MRKT call. 


time is the 2-word internal format time interval; 

when this interval elapses, the routine will 
be entered. If considered as a 2-element 
INTEGER*2 array: 
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time 

(i) 

is the 
time. 

high-order 

time 

( 2 ) 

is the 
time. 

low-order 


Notes: 

1 * M R RT requires a queue element; this should be considered 
when the IQSET function (Section 0.3.33) is executed. 

2 . If the system is busy, the time interval that elapses before 
the completion routine is run may be greater than that 
requested. 

For further information on scheduling completion routines, see the 

assembly language .MRKT request. Section 9.4.22. 

Errors: 

i = 0 Normal return 

- 1 No queue element was available; unable 
to schedule request. 

Example: 

INTEGERS TINT (2) 

EXTERNAL ARTN 


CALL MRKT (4,ARTN,TINT) 


MWAIT 


0.3.68 MWAIT (F/B Only) 


The MWAIT subroutine suspends main program execution of the current 
30 b until all messages sent to or from the other job have been 
transmitted or received. It provides a means for ensuring that a 
required message has been processed. MWAIT is used primarily in 
conjunction with the IRCVD and ISDAT calls, where no action is taken 
when a message transmission is completed. ' ' 
queue element; this should be considered 
(Section 0.3.33) is executed. 


This subroutine requires a 
when the IQSET function 


Form: CALL MWAIT 
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Errors: 

None. 

Example; 

See the example under ISDAT, Section 0.3.41. 


PRINT 


0.3.69 PRINT 


The PRINT subroutine causes output (from a specified string) to be 
printed at the console terminal. This routine can be used to print 
messages from completion routines without using the FORTRAN formatted 
I/O system. Control returns to the user program after all characers 
have been placed in the output buffer. 


The string to be printed may be terminated with either a null (0) byte 
or a 200 (octal) byte. If the null (ASCIZ) format is used, the output 
is automatically followed by a <CRXLF>. If a 200 byte terminates the 
string, no <CRXLF> is generated. 


In the F/B Monitor, a change in the job that is controlling terminal 
output is indicated by a B> or F>. Any text following the message has 
been printed by the job indicated (foreground or background) until 
another B> or F> is printed. When PRINT is used by the foreground 
job, the message appears immediately, regardless of the state of the 
background job. Thus, for urgent messages, PRINT should be used 
rather than ITTOUR. 

Form: CALL PRINT (string) 

where: string is the string to be printed. Note that all 

quoted literals used in FORTRAN subroutine 
calls are in ASCIZ format as are all strings 
produced by the SYSLIB string handling 
package. 

Errors: 

None. 

Example: 


CALL PRINT ('.THE COFFEE IS READY') 
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PURGE 


0.3.70 PURGE 

The PURGE subroutine is used to deactivate a channel without 
performing an ISAVES or a CLOSEC. Any tentative file currently 
associated with the channel is not made permanent. This subroutine is 
useful for keeping ENTERed (IENTER or .ENTER) files from becoming 
permanent directory entries. 

Form: CALL PURGE (chan) 

where: chan is the integer specification for the RT-11 

channel to be deactivated. 

Errors: 

None. 

Example: 

See the example under IENTER, Section 0.3.22. 


PUTSTR 


0.3.71 PUTSTR 

The PUTSTR subroutine writes a variable-length character string to a 
specified FORTRAN logical unit. PUTSTR may be used in main program 
routines or in completion routines but not in both in the same program 
at the same time. If PUTSTR is used in a completion routine, it must 
not be the first I/O operation on the specified logical unit. 

Form; CALL PUTSTR (lun,in,char) 

where: lun is the integer specification of the FORTRAN 

logical unit number to which the string is to 
be written. 
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in is the array containing the string to be 

written. 

char is an ASCII character that will be appended 

to the beginning of the string before it is 
output. If 0, the first character of "in" 
will be the first character of the record. 
This character is used primarily for carriage 
control purposes (see Section 0.3.13). 


Errors: 

None. 

Example: 

LOGICAL*! STRNG(81) 


CALL PUTSTR(7,STRNG,'0') !OUTPUT STRING WITH DOUBLE SPACING 


R50ASC 


0.3.72 R50ASC 

The R50ASC subroutine converts a specified number of Radix-50 
characters to ASCII. 


Form: CALL R50ASC (icnt,input,output) 


where: icnt 


input 


output 


is the integer number of ASCII characters to 
be produced. 

is the area from which words of Radix-50 
values to be converted are taken. Note that 
(icnt+2)/3 words are read for conversion. 

is the area into which the ASCII characters 
are stored. 


Errors: 

If an input word contains illegal Radix-50 codes, i.e., if the input 
word is greater (unsigned) than 174777 (octal) , the routine outputs 
question marks for the value. 
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Example: 


REAL*8 NAME 
LOGICAL*! OUTP(12) 


CALL R50ASC(12,NAME,OUTP) 


RAD50 



0.3.73 RAD50 

The RAD50 function provides a method of encoding RT-11 file 
descriptors in Radix—50 notation. The RAD50 function converts six 
ASCII characters from the specified area, returning a REAL*4 result 
which is the 2-word Radix-50 value. 

Form: a = RAD50 (input) 


where: input is the area from which 

characters are taken. 


the ASCII input 



The RAD50 call: 

A = RAD50 (LINE) 

is exactly equivalent to the IRAD50 call: 

CALL IRAD50 (6,LINE,A) 

Function Results: 

The 2-word Radix-50 value is returned as the function result. 



RCHAIN 


0.3.74 RCHAIN 

The RCHAIN subroutine allows a program to determine whether it has 
been chained to and to access variables passed across a chain. If 
RCHAIN is used, it must be used in the first executable FORTRAN 
statement in a program. RCHAIN cannot be called from a completion or 
interrupt routine. 


e 
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Form: CALL RCHAIN (flag ,var,wcnt) 


where: flag 


is an integer variable which will be set to 
-1 if the program has been chained to; 
otherwise, it is 0. 


var is the first variable in a sequence of 

variables with increasing memory addresses to 
receive the information passed across the 
chain (see Section 0.3.2). 

wcn t is the number of words to be moved from the 

chain parameter area to the area specified by 
var. RCHAIN moves "went" words into the area 
beginning at "var". 


Errors: 
None. 
Example: 


INTEGER*2 PARMS(50) 

CALL RCHAIN(IFLAG,PARMS,50) 

IF(IFLAG) GOTO 10 IGOTO 10 IF CHAINED TO 


RCTRLO 


0.3.75 RCTRLO 

The RCTRLO subroutine resets the effect of any console terminal CTRL 0 
(~0) command which was typed. After an RCTRLO call, any output 
directed to the console terminal will print until another CTRL O is 
typed. 

Form: CALL RCTRLO 


Errors: 


None. 


Example: 

CALL RCTRLO 

CALL PRINT ( 1 THE REACTOR IS ABOUT TO BLOW UP ) 
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REPEAT 


0.3.76 REPEAT 

The REPEAT subroutine concatenates a specified string with itself to 
produce the indicated number of copies. REPEAT places the resulting 
string in a specified array. 


Form: CALL REPEAT 

(in,out,i{,len{,err}}) 

where: in 

is the array containing the string to be 
repeated. 

out 

is the array into which the resultant string 
is placed. This array must be at least one 
element longer than the value of len, if 
specified. 

i 

is the integer number of times to repeat the 
string . 

len 

is the integer number representing the 

maximum length of the output string. 

err 

is the Logical error flag set if the output 
string is truncated to the length specified 
by len. 


Input and output strings may only specify the same array if the repeat 
count (i) is 1 or 0. When the repeat count is 1, this routine is the 
equivalent of SCOPY; when the repeat count is 0, "out" is replaced by 
a null string. The old contents of "out" are lost when this routine 

is called. 


Errors: 

Error conditions are indicated by "err", if specified. If err is 

given and the output string would have been longer than len 
characters, then "err" is set to .TRUE.? otherwise, "err is 

unchanged. 


Example: 

LOGICAL*! SIN(21) ,SOUT(101) 


CALL REPEAT(SIN,SOUT,5) 
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RESUME 


0.3.77 RESUME (F/B Only) 


The RESUME subroutine allows a job to resume execution 
program. A RESUME call is normally issued from an 
FORTRAN routine entered on I/O completion or because of 
request. (See Section 0.3.83 for more information.) 


of the main 
asynchronous 
a schedule 


Form: CALL RESUME 


Errors: 


None. 


Example: 

See the example under SUSPND, Section 0.3.83. 


O 


SCOMP 


0.3.78 SCOMP 


The SCOMP routine compares two character strings and 
integer result of the comparison. 


returns the 


Form: CALL SCOMP (a,b,i) 


or 


i = ISCOMP (a,b) 
where: a 

b 
i 


is the array containing the first string. 

is the array containing the second string. 

is the integer variable that receives the 
result of the comparison. 
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The strings are compared left-to-right, one character at a time, using 
the collating sequence specified by the ASCII codes for each 
character. If the two strings are not equal, the absolute value of 
variable i (or the result of the function ISCOMP) is the character 
position of the first inequality found in scanning left-to-right. 

If the strings are not the same length, the shorter one is treated as 
if it were padded on the right with blanks to the length of the other 
string. A null string argument is equivalent to a string containing 
only blanks. 

Notes: 

References to ISCOMP may not have quoted-string literals as arguments. 
Function Result: 

i <0 if a is less than b 

=0 if a is equal to b 

>0 if a is greater than b 

Example: 


LOGICAL*! INSTR(81) 


CALL GETSTR(5,INSTR,80) 

CALL SCOMP('YES',INSTR,IVAL) 

IF(IVAL) GOTO 10 !IF INPUT STRING IS NOT YES GOTO 10 




SCOPY 


0.3.79 SCOPY 

The SCOPY routine copies a character string from one array to another. 
Copying stops either when a null (zero) character is encountered or 
when a specified number of characters have been moved. 

Form: CALL SCOPY (in ,out{ ,len{ ,err } }) 

is the array containing the string to be 
copied. 

is the array to receive the copied string. 
This array must be at least one element 
longer than the value of len, if specified. 


where: in 

out 
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len is the integer number representing the 

maximum length of the output string. The 
effect of len is to truncate the output 
string to a given length, if necessary. 

err is a Logical variable that receives the error 

indication if the output string was truncated 
to the length specified by len. 

The input (in) and output (out) arguments may specify the same array. 
The string previously contained in the output array is lost when this 
subroutine is called. 

Errors: 

Error conditions are indicated by "err", if specified. If err is 
given and the output string was truncated to the length specified by 
"len", then "err" is set to .TRUE.; otherwise, "err" is unchanged. 

Example: 

SCOPY is useful for initializing strings to a constant value, for 
example: 


L0GICAL*1 STRING(80) 

CALL SCOPY('THIS IS THE INITIAL VALUE',STRING) 


SECNDS 


0.3.80 SECNDS 

The SECNDS function returns the current system time, in seconds past 
midnight, minus the value of a specified argument. Thus, SECNDS can 
be used to calculate elapsed time. The value returned is 
single-precision floating point (REAL*4). 

Form: a = SECNDS (atime) 

where: atime is a REAL*4 variable, constant, or expression 

whose value is subtracted from the current 
time-of-day to form the result. 


Notes: 

This function does floating-point arithmetic. Elapsed times may also 
be calculated by using the GTIM call and the INTEGER*4 support 
functions. 

Function Result: 

The function result (a) is the REAL*4 value returned. 
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Example: 


C START OF TIMED SEQUENCE 
Tl=SECNDS (0.) 

C 

C CODE TO BE TIMED GOES HERE 
C 

DELTA=SECNDS(Tl) !DELTA IS ELAPSED TIME 



0.3.81 


STRPAD 


STRPAD 


The STRPAD routine pads a character string with rightmost blanks until 
that string is a specified length. This padding is done in place; 
the result string is contained in its original array. If the present 
length of the string is greater than or equal to the specified length, 
no padding occurs. 

Form: CALL STRPAD (a,i{,err}) 

is the string to be padded. 

is the integer length of the desired result 
string. 

is the Logical error flag that is set to 
.TRUE. if the string specified by a exceeds 
the value of i in length. 



Errors: 


Error conditions are indicated by "err", 
given and the string indicated is longei 
set to .TRUE.; otherwise, the value of 


if specified. If 
than "i" characters 
"err" is unchanged. 


"err" 

"err" 


is 

is 


Example: 


This routine is especially useful for preparing strings to be output 
in A-type FORMAT fields. For example: 


LOGICAL*! STR(81) 


100 



CALL STRPAD(STR,80) 

PRINT 100,(STR(I) ,1=1,80) 
FORMAT(80A1) 


!ASSURE 80 VALID CHARACTERS 
!PRINT STRING OF 80 CHARACTERS 
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SUBSTR 


0.3.82 SUBSTR 

The SUBSTR routine copies a substring from a specified position in a 
character string. If desired, the substring may then be placed in the 
same array as the string from which it was taken. 

Form: CALL SUBSTR ( in ,out, i{ ,len}) 

where: in is the array from which the substring is 

taken. 

out is the array to contain the substring result. 

This array must be one element longer than 
"len", if specified. 


i is the integer character position in the 

input string of the first character of the 
desired substring. 

len is the integer number of characters 

representing the maximum length of the 
substring. 

If a maximum length (len) is not given, the substring contains all 
characters to the right of character position "i" in array "in". If 
"len" is equal to zero, "out" is replaced by the null string. The old 
contents of array "out" are lost when this routine is called. 


Errors: 


None. 
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SUSPND 


0.3.83 SUSPND (F/B Only) 

The SUSPND subroutine suspends main program execution of the current 
job and allows only completion routines (for I/O and scheduling 
requests) to run. 

Form: CALL SUSPND 

Notes: 

1. The monitor maintains a suspension counter for each job. 
This count is decremented by SUSPND and incremented by RESUME 
(see Section 0.3.77). A job will actually be suspended only 
if this counter is negative. Thus, if a RESUME is issued 
before a SUSPND, the latter function will return immediately. 

2. A program must issue an equal number of SUSPNDs and RESUMES. 

3. A RESUME subroutine call from the main program or from a 
completion routine increments the suspension counter. 

4. A SUSPND subroutine call from a completion routine decrements 
the suspension counter but does not suspend the main program. 
If a completion routine does a SUSPND, the main program 
continues until it also issues a SUSPND, at which time it is 
suspended and will require two RESUMES to proceed. 

5. Because SUSPND and RESUME are used to simulate an ITfaAIT (see 
Section 0.3.49) in the monitor, a RESUME issued from a 
completion routine and not matched by a previously executed 
SUSPND may cause the main program execution to continue past 
a timed wait before the entire time interval has elapsed. 

For further information on suspending main program execution of the 
current job, see the assembly language .SPND request. Section 9.4.39. 

Errors: 

None. 
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Example: 

INTEGER IAREA(4) 

COMMON /RDBLK/ IBUF(256) 
EXTERNAL RDFIN 


IF(IREADF(256,IBUF,IBLK,ICHAN,IAREA,RDFIN).NE.0) GOTO 1000 
C GOTO 1000 FOR ANY TYPE OF ERROR 
C 

C DO OVERLAPPED PROCESSING 


CALL SUSPND !SYNCHRONIZE WITH COMPLETION ROUTINE 


END 

SUBROUTINE RDFIN(IARG1,IARG2) 
COMMON /RDBLK/ IBUF(256) 


CALL RESUME !CONTINUE MAIN PROGRAM 


END 


TIMASC 


0.3.84 TIMASC 

The TIMASC subroutine converts a 2-word internal format time into 
ASCII string of the form: 


hh:mm:ss 

where: 

hh 

is 

the 

2-digit 

hours indication 


mm 

is 

the 

2-digit 

minutes 

indication 


ss 

is 

the 

2-digit 

seconds 

indication 


Form: CALL TIMASC (itime,strng) 


an 
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where: itime is the 2-word internal format time to be 

converted. itime (1) is the high-order time, 
itime (2) is the low-order time. 

strng is the 8-element array to contain the ASCII 

time. 


Errors: 

None. 

Example: 

The following example determines the amount of time until 5 p.m. and 
prints it. 


INTEGERM J1,J2,J3 
LOGICAL*! STRNG(8) 


CALL JTIME(17,0,0,0,Jl) 

CALL GTIM{J2) 

CALL JJCVT(Jl) 

CALL JJCVT(J2) 

CALL JSUB(Jl,J2,J3) 

CALL JJCVT(J3) 

CALL TIMASC(J3,STRNG) 

TYPE 99,(STRNG(I),1=1,8) 

99 FORMAT(' IT IS ',8A1,' TILL 5 P.M.') 


TIME 


0.3.85 TIME 

The TIME subroutine returns the current system time-of-day as an 


character 

ASCII string 

of 

the 

form: 



hh:mm: 

ss 






where: 

hh 

is 

the 

2 -digit 

hours indication 


mm 

is 

the 

2 -digit 

minutes 

indication 


ss 

is 

the 

2 -digit 

seconds 

indication 
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Form: CALL TIME (strng) 

where: strng is the 8-element array to receive the ASCII 

time. 

Notes: 

A 24-hour clock is used, e.g., 1:00 p.m. is represented as 13:00:00. 
Errors: 

None. 

Example: 

LOGICAL*l STRNG(8) 

CALL TIME(STRNG) 

TYPE 99,(STRNG(I) ,1 = 1,8) 

99 FORMAT (' IT IS NOW ',8A1) 


TRANSL 


0.3.86 TRANSL 


The TRANSL routine performs character translation on a specified 
string. The TRANSL routine requires approximately 64 words on the R6 
stack for its execution. This space should be considered when 
allocating stack space. 


Form: CALL TRANSL 

where: in 

out 

r 

P 


(in ,out ,r { ,p}) 

is the array containing the input string. 

is the array to receive the translated 

string. 

is the array containing the replacement 

string. 

is the array containing the characters in 
"in" to be translated. 


The string specified by array "out" is replaced by the string 
specified by array "in", modified by the character translation process 
specified by arrays "r" and "p". If any character position in "in" 
contains a character which appears in the string specified by "p", it 
is replaced in "out" by the corresponding character from string "r". 
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If the array "p" is omitted, it is assumed to be the 127 7-bit ASCII 
characters arranged in ascending order, beginning with the character 
whose ASCII code is 001. If strings "r" and "p" are given and differ 
in length, the longer string is truncated to the length of the 
shorter. If a character appears more than once in string "p"/ only 
the last occurrence is significant. A character may appear any number 
of times in string "r". 

Errors: 

None. 

Examples: 

The following example causes the string in array A to be copied to 
array B. All periods within A become minus signs, and all question 
marks become exclamation points. 

CALL TRANSL(A,B, 1 -!' ,* . ? 1 ) 

The following is an example of TRANSL being used to format character 
data. 


C 

C 

c 

c 

c 

c 

c 

c 

c 

10 


20 

c 

c 

c 

c 

c 

c 

c 

c 

c 


L0GICAL*1 STRING(27),RESULT(27),PATRN(27) 

SET UP THE STRING TO BE REFORMATTED 

CALL SCOPY( 1 THE HORN BLOWS AT MIDNIGHTSTRING) 

00000000011111111112222222 
12345678901234567890123456 
THE HORN BLOWS AT MIDNIGHT 

NOW SET UP PATRN TO CONTAIN THE FOLLOWING PATTERN: 

16,17,18,19,20,21,22,23,24,25,26,15,1,2,3,4,5,6,7,8,9,10,11,12,13,14,0 

DO 10 1=16,26 
PATRN(I-15)=I 
PATRN(12)=15 
DO 20 1=1,14 
PATRN(1+12)=1 
PATRN(27)=0 

THE FOLLOWING CALL TO TRANSL REARRANGES THE CHARACTERS OF 
THE INPUT STRING TO THE ORDER SPECIFIED BY PATRN: 


CALL TRANSL(PATRN,RESULT,STRING) 

RESULT NOW CONTAINS THE STRING 'AT MIDNIGHT THE HORN BLOWS' 
IN GENERAL, THIS METHOD CAN BE USED TO FORMAT INPUT STRINGS 
OF UP TO 127 CHARACTERS. THE RESULTANT STRING WILL BE 
AS LONG AS THE PATTERN STRING (AS IN THE ABOVE EXAMPLE). 
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TRIM 


0.3.87 TRIM 

The TRIM routine shortens a specified character string by removing all 
trailing blanks. A trailing blank is a blank that has no non-blanks 
to its right. If the specified string contains all blank characters, 
it is replaced by the null string. If the specified string has no 
trailing blanks, it is unchanged. 

Form: CALL TRIM (a) 

where: a 


Errors: 

None. 

Example: 

L0GICAL*1 STRING(81) 

ACCEPT 100,(STRING(I) ,1=1,80) 
100 FORMAT(80A1) 

CALL SCOPY(STRING,STRING,80) 
CALL TRIM(STRING) 


I MAKE ASCIZ 

(TRIM TRAILING BLANKS 


is the array containing the string to be 
trimmed. 


UNLOCK 


0.3.88 UNLOCK 

The UNLOCK subroutine releases the User Service Routine (USR) from 
memory if it was placed there by the LOCK routine. If the LOCK 
required a swap, the UNLOCK loads the user program back into memory. 
If the USR does not require swapping, the UNLOCK involves no I/O. 
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Form: CALL UNLOCK 

Notes: 

1. It is important that at least as many UNLOCKS are given as 

LOCKS. If more LOCKs were done, the USR remains locked in 

memory. It is not harmful to give more UNLOCKS than are 
required; those that are extra are ignored. 

2. When running two jobs in the F/B system, use the LOCK/UNLOCK 
pairs only when absolutely necessary. If one job LOCKS the 
USR, the other job cannot use the USR until it is UNLOCKed. 
Thus, the USR should not be LOCKed unnecessarily, as this may 
degrade performance in some cases. 

3. In an F/B System, calling the CSI (ICSI) with input coming 
from the console terminal performs an implicit UNLOCK. 

For further information on releasing the USR from memory, see the 
assembly language .LOCK/.UNLOCK requests. Section 9.4.20. 

Errors; 

None. 

Example: 


C GET READY TO DO MANY USR OPERATIONS 
CALL LOCK !DISABLE USR SWAPPING 

C PERFORM THE USR CALLS 


C FREE THE USR 
CALL UNLOCK 


VERIFY 


0.3.89 VERIFY 

The VERIFY routine determines whether each character of a specified 
string occurs anywhere in another string. If a character does not 
exist in the string being examined, VERIFY returns its character 
position in string "b". If all characters exist, VERIFY returns a 
zero. 
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Form: CALL VERIFY (a,b,i) 

or 

i = IVERIF (a ,b) 


where: 

a 

is the array containing the 
scanned. 

string to 

be 


b 

is the array containing the string 

characters to be accepted in a. 

of 


i 

is the integer result of the 

verification. 



Notes: 

Quoted-string literals must not be used with the IVERIF function 
subprogram. They may be used with the VERIFY subroutine subprogram. 

Function Result: 

i = 0 if all characters of "a" exist in "b"; also if 

"a" is a null string. 

= n where n is the character position of the first 

character in "a" that does not appear in "b"; if 
"b" is a null string and "a" is not, i equals 1. 

Example: 

The following example accepts a 1- to 5-digit unsigned decimal number 
and returns its value. 

LOGICAL*! INSTR(81) 


CALL VERIFY(INSTR(IPOS) 0123456789' ,1) 
IF(I.EQ.l) STOP 'NUMBER MISSING' 
IF(I.EQ.O) I=LEN(INSTR)-IPOS+1 
IF(I.GT.5) STOP 'TOO MANY DIGITS' 

NUM=IVALUE(INSTR(IPOS),1) 


END 

FUNCTION IVALUE(ARRAY,I) 
LOGICAL*l ARRAY(1) 

DECODE(I,99,ARRAY) IVALUE 
99 FORMAT(15) 

END 
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Absolute address 

Absolute block numbers 

Absolute section 

Addressing mode 

Allocation 

Alphanumeric character 
string 

Argument 

Argument block 

Array 

ASCII 

Assembler 

Assembler directives 


A binary number that is assigned as the 
address of a fixed memory storage 
location. 

Any blocks which use block 0 of a physical 
device as a base. Relative blocks use the 
start of a file as a base. 

That portion of a program in which the 
programmer specifies the physical 
(absolute) locations of data items, using 
the .ASECT assembler directive. 

The portion of a PDP-11 machine 
instruction which specifies how the 
argument is to be referenced. 

Assigning a resource to a job. 

A command string containing any of the 26 
alphabetic characters A-Z, the numeric 
characters 0-9, space and certain special 
characters. 

A variable or constant which is given in 
the call of a subroutine as information to 
it; a variable upon whose value the value 
of a function depends; the known 
reference factor necessary to find an item 
in a table or array (i.e., the index). 

A block of memory used to transmit 
programmed request arguments to the 
monitor. 

A set or list of elements, usually 
subscripted variables or data. 

American Standard Code for Information 
Interchange. Established by American 
National Standards Institute to 
standardize a binary code for alphanumeric 
characters. 

A program that translated symbolic opcodes 
into machine language and assigns memory 
locations for variables and constants. 

The mnemonics used in the assembly 
language programs to control or direct the 
assembly process. 
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Assembly language 

A symbolic language that translates 
directly into machine language 
instructions. Usually there is a 
one-to-one relation between assembly 
language instructions and machine language 
instructions. 

Asynchronous 

1. Pertaining to the scheduling of 

hardware operations by ready and done 
signals rather than by time intervals. 

2. Pertaining to the method of data 

transmission in which each character 
is sent with its own synchronizing 
information. 

Autoincrement mode 

Mode of operation wherein the contents of 
the register are incremented immediately 
after being used as the address of the 
operand. 

Background program 

A program operating automatically, under 
low priority, when higher priority 
(foreground) programs are not using system 
resources. 

Backup file 

A copy of a file created for protection in 
case the primary file is inadvertently 
destroyed. 

Bad blocks 

A defective block of storage on any type 
of magnetic storage medium that produces a 
hardware error when attempting to read or 
write in the block. 

Base address 

A given address from which an absolute 
address is derived by combination with a 
relative address. An address constant. 

Base segment 

The portion of an overlayed program that 
is always memory resident; same as root 
segment. 

Baud 

A unit of signaling speed. In a code in 
which all characters have the same length, 
one baud corresponds to a rate of one 
signal element per second, usually one bit 
per second. 

Binary 

Pertaining to the number system having a 
base or radix of two. In this system 
numbers are represented by Is and Os. 
Counting to ten in binary: 1, 10, 11, 
100, 101, 110, 111, 1000, 1001, 1010. 
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Bit 


Block-replaceable 

Blocks 


Bootstrap 

Bottom address 

Bounds 

Breakpoint 

Buffer 

Byte 

Carry bit 

Central processing unit 

Chaining 

Channel number 


Contraction of "Binary digit", a bit is 
the smallest unit of information in a 
binary system of notation. It is the 
choice between two possible states, 
usually designated one (1) and zero (0)^ 

See Random-Access. 

A set of consecutive machine words, 
characters or digits handled as a unit, 
particularly in reference to I/O. Each 
type of mass storage has its own block 
size, its own smallest unit of storage 
( e *9-/ PDP-11 DECtape has 256 
(decimal) 16-bit words per block). See 
Data Block. 

A program whose purpose is to load and 
(usually) start a complex system of 
programs. 

The lowest memory address in which a 
program is located. 

The limits a program may operate within. 

A preset point in a user program where 
control passes to a debugging routine. 

A temporary storage area which may be a 
special register or an area of storage. 
Buffers are often used to hold data being 
passed between processes or devices which 
operate at different speeds or different 
times. 

A group of binary digits usually operated 
upon as a unit; 8 bits is usually a byte 
(1/2 a PDP-11 word). 

A bit in the program status word 
indicating a carry from the most 
significant bit in the operation; also a 
common method of indicating a program 
request failure. 

The part of the computer containing the 
Arithmetic and Logical Unit, the 
Instruction Control Unit, timing 
generators and I/O interfaces of the basic 
system. 

A programming technique which involves 
dividing a routine into sections with each 
section terminated by a call to the next 
section. 

Logical identifier in the range 0 to 255 
(decimal) assigned to a file used by RT-11 
monitor. Data blocks in an open file may 
be referred to by channel number. 
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Channnel status word 

A word associated with each I/O channel in 
RT-11 that perserves the status of that 
channel. 

Character-oriented 

Referring to editing operations on a 

single character. See also Line-oriented. 

Checksum 

A value representing the sum of all bytes 
in a program. When the program is loaded, 
the sum of the bytes can be compared with 
the checksum to make sure that the entire 
program has been loaded correctly. 

Clock 

A time-keeping or frequency-measuring 

device within the computer system. 

Closed location 

A location whose contents are not 

available for examination and change. 

Co-resident overlay 
routines 

Overlay routines that are simultaneously 
resident in memory. 

Command string 

A series of characters which specify the 
input/output devices, files, and switches. 

Command String 
Interpreter 

The portion of the RT-11 system software 
which accepts an ASCII string input and 
interprets the string as input and output 
files and switches. 

Completion routine 

An optional user-supplied routine that is 
called at the completion of an operation 
and is generally used to allow the user to 
handle asynchronous events. 

Compress 

To collect into one area all the free 
(unused) blocks that are interspersed in 
the directory and files on a specified 
device. 

Concatenate 

To combine many files into one file. 

Condition codes 

The four bits of the Program Status Word 
in the PDP-11 Processor that preserve the 
results (negative, zero, carry, overflow) 
of the instruction just completed. 

Configuration 

A particular selection of computer, 
peripherals, and interfacing equipment 
that are functioning together. A list of 
the devices of a computer system. 

Console device 

The interface, or communication device, 
between the operator and the computer, 
that contains indicator lights, switches, 
knobs and sometimes a keyboard to permit 
manual operation of the device. 

Constant register 

A logical register in ODT or PATCH that is 
used to store an often-used constant. 
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Context switching 

The saving of key registers and other 
memory areas prior to switching between 
jobs, as in timesharing or 
multiprogramming. 

Contiguous 

Code that resides in memory or on a 
peripheral device immediately adjacent to 
other sections of code or data. 

Control Section (CSECT) 

A named, contiguous part of a program. 
CSECTs are denoted by the directives 

.CSECT" and ".ASECT" in the MACRO 

Assembler Language. CSECTs are collected 
and assigned addresses by the Linker. 

Control statement 

A job statement that is used to issue 
commands to the system through the input 
stream. 

Core memory 

The main high-speed storage of a computer 
in which binary data is represented by the 
switching polarity of magnetic cores. 
Semi-conductor memory is higher speed than 
core memory, but semi-conductor memory is 
more expensive and volatile. 

Cross reference table 
(CREF) 

A list of all or a subset of symbols in 
source program and statements where they 
were defined or used. 

Cursor 

On a display device, a symbol that appears 
to indicate the location of the pointer. 

Data block 

A logical grouping of data, usually 
associated with input or output. Typical 
data block involved in RT-11 are 256 words 
long. 

Data format 

The form or structure of information, 
particularly in an I/O file. RT-11 has 
several standard data formats such as 
ASCII and formatted binary. 

Data image 

A job statement that is used to define 
data for system programs and user programs 
through the input stream. 

Debug 

To detect, locate, and correct mistakes in 
a program. 

Default 

A specification assigned by a system 
program when user specification is 
omitted. 

Delimiter 

A character that separates, terminates and 
organizes elements of a statement or 
program. 

Device block 

A section of code that specifies a 
physical device and filename for an RT-11 
programmed request. 
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Device directory 
listing 


Device handlers 


Direct assignment 

Directive 

Directory 

Disk 

Display unit 
Double buffered I/O 


Dummy file 
Editor 

EMT 

Entry point 


A list of all files on a specified device. 
The list contains all files with 
associated creation dates, total free 
blocks on the device, and number of blocks 
used by files. Magtape and cassette 
directories omit some information. See 
Directory. 

Routines that perform I/O for specific 
storage devices and translate logical 
block numbers to physical disk, tape or 
drum addresses. These routines also 
handle error recovery and provide device 
independence in conjunction with operating 
systems. 

User definition of a symbol and its 
associated value. 

See Assembler directives. 

An area of a mass storage device that 
describes the layout of the data on that 
device in terms of file names, length and 
location. 

A mass storage device. Basic unit is an 
electromagnetic platter on which data is 
magnetically recorded. Features random 
access and faster access time than 
magnetic tape. 

A device that provides a visual 
representation of data. 

An input (or output) operation using two 
buffers to achieve more efficient usage of 
computer time. While one buffer is being 
used by the CPU program, the other is 
being read from (or written to) by an I/O 
device. 

A file used only to hold space on a 
storage device. 

A program which interacts with the 
programmer to enter new programs into the 
computer and edit them as well as modify 
existing programs. Editors are language 
independent and will edit anything in 
alphanumeric representation. 

A PDP-11 machine instruction (operation 
codes from 104000-1043777). EMTs are most 
often used for monitor communication. 

A point in a subroutine to which control 
is transferred when the subroutine is 
called. 
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Entry point table 

Entry symbol 

Error flag 

Exception 

Expressions 

External symbol 

Fatal error 

File allocation scheme 

File gap 

File-structured device 

Filler characters 

Flag 

Floating-point 


A table, kept by the Librarian program, of 
the names and locations of the routines 
available in the library. 

A global symbol defined in an object 
module that can be referred to by other 
object module. 

Condition indicating an error has 
occurred. If the C bit is set on return 
from an RT-11 call, an error occurred. 
Thus, the C bit set is the RT-11 error 
flag. 

An unusual condition (e.g., a floating 
point exception is an overflow). 

A combination of variables, constants, and 
operators (as in a mathematical 
expression). 

A symbolic name which is defined in one 
assembly or compilation and can be 
referenced in another. The .GLOBL 
directive is used to indicate external 
symbols to the MACRO assembler. 

An error which makes continued processing 
impossible (e.g., running out of symbol 
table space is usually a fatal error). 

The method used to store data on I/O 
devices. RT-11 uses a contiguous 
structure. 

A fixed length of blank tape separating 
files on a recording medium. 

A device on which data is given names and 
arranged in files (e.g., disk, DECtape, 
magtape, or cassette). 

Null characters output to a device to give 
it time to perform unusually long 
operations (such as return the carriage) 
without explicitly waiting. 

A variable or register used to record the 
status of a program or device. In the 
latter case it is sometimes called a 
device flag. 

A number system in which the position of 
the radix point is indicated by one part 
(the exponent part) , and another part 
represents the significant digits, the 
fractional part (e.g., 5.39X10(8) for 
Decimal; 137.3X8(4) for Octal; 
101.10X2(13) for Binary). 
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Foreground program 

A program of high priority that utilizes 
machine facilities when and as needed, but 
allows less critical background work to be 
performed in otherwise unused time. 

Formatted binary block 

A data structure used to hold binary 
information, usually to be read or written 
to a data file. For example, an object 
module produced by the MACRO assembler 
consists of formatted binary blocks. 

Fragmented 

Having many empty entries scattered over a 
device. 

Free blocks 

Areas of a file structured device which 
are unused. 

General registers 

A set of eight general purpose registers 
available for use as accumulators, as auto 
index registers or as pointers. General 
registers 6 and 7 serve as the hardware 
stack pointer and program counter 
respectively. 

Global symbol 

Any symbol accessible to other programs. 
Linkage must be supplied by a linker. 

Global symbol directory 

The portion of an object module which 
describes all external symbols and CSECT 
names which are defined or referenced by 
the object module. 

Handler 

See Device handler 

Hardware mode 

For magnetic tapes and cassettes. Allows 
full user control over position and record 
size (as opposed to software mode.) 

• 

High level language 

A language in which single statements may 
result in more than one machine language 
instruction, e.g., BASIC, FORTRAN, COBOL. 

Image mode 

A mode of data transfer in PIP in which a 
file is copied without change of any kind. 

Implied argument 

An argument which is assumed by the 
program, whether or not it is explicitly 
stated by the user. 

Indexing 

Using a variable index register as an 
offset into a table. 

Initialize 

To set counters, switches, addresses and 
variables to zero or other starting 

values. 
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Input stream The sequence of control statements and 

data images submitted to the operating 
system on an input device especially 
dedicated for this purpose. 

Internal symbol a symbolic name which is known only within 

the assembly or compilation where it is 
defined. Symbols are internal by default. 

Interrupt service routine Routine entered when an external interrupt 

occurs. 


Interrupt 


Iterations 

Job 


Job status word 

Keyboard monitor (KMON) 

Keyword 

Label 

LDA format file 


1. To break the normal operation of the 
routine being executed and pass 
control to a specific location, 
generally accompanied by saving the 
state of the current routine so that 
control can return later. 

2. The signal which causes the break. 

Repetitions of a portion of a program. 

The largest definable collection of 
elements describing the work to be 
performed. The purpose of the job is to 
collect and describe the logical work 
which is to be performed. A job is 
composed of control statements and data 
images. 

A word in the RT-11 communications region 
containing bit flags indicating the status 
of the program currently in memory. 

The program that provides communication 
between the user at the console and the 
RT-11 system. 

A symbol that identifies a parameter. 

One or more characters used to identify a 
source language statement or line. 

See Load image file. 


Library 


Library header 


Light pen 


A collection of standard routines which 
can be incorporated into other programs. 

Section of code that contains the current 
status of the library, including version, 
date and time of creation or update, 
relative starting address of entry point 
table, number of EPT entries and placing 
of next module to be inserted into the 
library file. 

A device resembling a pencil or stylus 
which can detect a fluorescing spot on a 
CRT screen. Used to input information to 
a CRT display system. 
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Line-oriented 

Referring to editing operations on an 
entire line of text. See also 

Character-oriented. 

Load image file 

A program that can be executed in 
stand-alone environment without the aid of 
relocation. 

Local symbol 

A symbol used only within the program in 
which it is defined (all non-global 
symbols). 

Location counter 

A counter kept by an assembler to 
determine the address assigned to an 
instruction or constant being assembled. 

Logical name 

A user-defined name assigned as an 
alternate name for a physical device. 
Useful for redirecting I/O when device 
originally specified is unavailable. 

Loop 

A sequence of instructions that is 
executed repeatedly until a terminal 
condition occurs. Also, used as a verb 
meaning to execute this circle of 
instructions while waiting for the ending 
condition. 

Macro 

An instruction in a source language that 
is equivalent to a specified sequence of 
machine instructions, or a command in a 
command language that is equivalent to a 
specified sequence of commands. 

Macro symbol 

Symbol used as macro name in operator 
field. 

Mainstream code 

Any code which is not executing as a 
result of a completion routine. 

Mask word 

A combination of bits that is used to 
access selected portions of any word, 
character, byte, or register while 

retaining other parts for use. Also, to 
clear these selected locations with a 
mask. 

Memory address 

An address in memory used to store data. 

Memory image 

An exact copy of a portion of memory. 
RT-11 save image files (.SAV) are memory 
images. 

Mnemonic 

Alphabetic representation of a function or 
octal machine instruction. 

Mode 

A state or method of program operation. 
Command mode causes user input to be 
interpreted as a command? text mode 

causes user input to be interpreted as 
alphanumeric data, etc. 
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Module 

A routine which handles a particular 

function. 

Monitor 

The collection of routines which schedules 
resources, I/O, system programs, and user 
programs, and obeys keyboard commands in a 
Monitor System. 

Monitor System 

Editors, assemblers, compilers, loaders, 
interpreters, data management programs and 
other utility programs all automated for 
the user by a monitor. 

Multi-region 

A term describing the RT-11 overlay 

structure in which there may exist 

multiple independent areas of high-speed 
memory (regions) in which overlays may 
occur. 

Nesting 

1. Including a program loop inside 

another program loop, or other similar 
occurrences within one another. 

2. Algebraic nesting such as (A+B+(C+D)) 

where execution proceeds from the 

innermost level to the outermost 

level. 

Nonfile-structured 
device 

A device that is used only for input or 
output, and not storage, of a file (e.g., 
line printer, card reader, terminal, or 
paper tape). 

Nonfile-structured 
.LOOKUP (or .ENTER) 

A .LOOKUP (or .ENTER) with a null file¬ 
name, that permits access to a device by 
reference to absolute block numbers, 
rather than block numbers relative to a 
file. 

NonRT-11 directory- 
structured 

A device having no standard RT-11 
directory at its beginning. This includes 
magtape and cassette, and any devices for 
which user-defined directories have been 
written. 

Null 

Characters with ASCII code 000. 

Object code 

The result after assembling or compiling 
source code. Machine code. 

Off-line 

Pertaining to equipment, devices or events 
which are not under direct control of the 
computer. 

Offset 

The difference between a location of 

interest and some known base location. 

On-line 

Pertaining to equipment, devices and 
events which are in direct communication 
with the CPU and thereby under its control 
in some way. 

Open location 

A location whose contents have been 
printed for examination; contents can be 
changed. 
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Operand 

1. A quantity which is affected, 

manipulated or operated upon. 

2. The contents of the field following 

the operator of an assembler 

instruction. 

Operating system 

A program for automating a programmer's 
use of software. A Monitor System. 

Operator 

That symbol or code which indicates an 
action or operation to be performed. 

Output stream 

Output data issued by the operating system 
on the processing program to an output 
device especially designated for this 
purpose. 

Overlay 

The technique of repeatedly using the same 
area of memory during different stages of 
a program. When one routine is no longer 
needed in memory, another routine can 
replace all or part of it. Over-laying 
replaces parts of programs; chaining 
replaces the whole program. 

Overlay segment 

A section of code handled as a unit. This 
segment of code can overlay code already 
in memory or can be overlaid by another 
overlay segment. 

Overlay-structured 

A term describing a program which does not 
entirely reside in high-speed memory at 
any instant. Portions of the program are 
brought into memory when needed. 

Page of text 

That portion of a file delimited by form 
feed characters, generally 50-60 lines 
long: corresponds approximately to a 
physical page of program listing. 

Parameter 

A variable or an arbitrary constant 
appearing in a mathematical expression, 
each value of which restricts or 
determines the specific form of the 
expression. 

Patch 

To modify a routine in a rough or 
expedient way, usually by modifying the 
binary code rather than reassembling it. 

Peripheral devices 

In a data processing system, any device 
distinct from the central processing unit, 
which may provide the system with outside 
storage or communication. 

Permanent file 

An output file that is stored in memory 
for later use. 

Permanent symbol 

Instruction mnemonics, assembler 
directives, and macro directives 
incorporated in the assembler. 
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Physical device 

An input, output, or storage device 

associated with the Central Processing 
Unit. 

Physical name 

A 2- or 3-character name identifying a 
physical device. The first two characters 
are alphabetic and identify the device; 
the third character is numeric and 
identifies the unit. 

PIC code 

Abbreviation for Position Independent 
Code. (Code which can operate properly 
wherever it may be loaded in memory). 

Pointer 

1. A location containing the address to 
another location. 

2. In the EDIT program, a movable 

reference pointer normally located 

between the character most recently 
operated upon and the next character 
in the buffer; represents the current 
position of the Editor in the text. 

Positional parameter 

A parameter that must appear in a 
specified position in an ordered group of 
parameters. 

Proceed count 

In a program loop, the number of times the 
breakpoint is to be encountered before 
suspension of program execution. 

Processor status register 

A register that indicates the current 
priority of the processor, the condition 
of the previous operation, and other basic 
control items. 

Program counter 

A register in the CPU that holds the 
address of the current instruction being 
executed plus two; in other words, it 
holds the address of the next instruction 
unless the current instruction causes a 
jump. 

Program sections 

See Control section. 

Programmed requests 

Machine language instruction which is used 
to invoke a monitor service for the 
issuing program. 

Purge 

Deactivate a channel without taking any 
other action. 

Radix 

The base of a number system; the number 
of digit symbols required by a number 
system. 

Random-access 

A means of accessing data in a random 
order (independently of the data's 

physical or relative position on the 

device). 
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Real time 

1. Pertaining to the actual time during 
which a physical process takes place. 

2. Pertaining to the performance of 

computer activity which occurs fast 
enough to influence the related 

physical process. 

Real time system 

A system in which computation is performed 
while a related physical process is 
occurring so that the results of the 
computation can be used in guiding the 
physical process. 

Record 

A collection of related items of data 
treated as a unit. Example: A line of 
source code. 

Reentry address 

The Start address -2. Allows the user 
program to reset itself internally, and 
resume operation. 

Region number 

A number which is used to identify a 
portion of memory to the Linker for the 
purpose of describing an overlay 

structure. 

Relative address 

A number specifying the difference between 
an absolute address and a base address. 

Relocatable code 

Code written so that it can be located and 
executed in any part of memory, once it 
has been linked by Linker. 

Relocatable object modules 

A set of instructions which are written so 
that the module can be loaded and executed 
in any memory area. 

Relocatable symbols 

Symbolic names whose associated value is 
an offset from the base (beginning) of a 
control section. Such a symbol's value 
depends on the address of the control 
section and must be relocated each time 
the control section is assigned an address 
by the Linker. 

Relocation 

To move a routine from one portion of 
storage to another and to adjust the 
necessary address references so that the 
routine can be executed in the new 

location. 

Relocation directory 

A portion of an object module which 

describes and identifies all occurrences 
of relocatable symbols in the object 

module. 

Repeat block 

Block of code to be repeated a defined 
number of times. 

Repeat count 

The number of times a block of code is to 
be repeated. 
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stored 


Resident 

Resident monitor (RMON) 

Root segment 

RT-11 directory- 
structured 

Scratch area 
Scrolling 

Sentinel file 

Sequence number 

Sequential-access 

Software mode 

Source code 

Source file 

Stack 


In memory, as opposed to being 
externally. 

The permanent memory-resident part of 
RT-11. Contains console terminal service, 
the error processor, the system device 
handler, the EMT processor, and system 
tables. 

See Base segment. 

A device having a standard RT-11 directory 
at its beginning that is updated as files 
on the device are manipulated (for 
example, disk and DECtape). 

Any memory or registers used for temporary 
storage of partial results. 

On a display screen, when the maximum 
number of lines are on the screen, the top 
line is deleted, and all text moves up one 
line, permitting one new line of display 
at the bottom of the screen. The visual 
effect is similar to the rolling up of a 
scroll. 

The last file on cassette tape; contains 
only a header record and represents 
logical end-of-tape. 

The number in a cassette directory which 
designates where a file is placed (in 
sequence), when that file has been 
continued on more than one cassette. 

A means of accessing data in which records 
or blocks are read one after another from 
the device (as opposed to random-access). 

For magnetic tapes and cassettes, the mode 
of operation when device access is through 
any RT-11 system program. 

Text, usually in the form of an ASCII 
formatted file, which represents a 
program. Such a file can be processed by 
an appropriate system program (MACRO or 
FORTRAN) to produce an object module. 

A file to be used as input to a 
translating program such as MACRO or 
BASIC. 

An area of memory set aside by the 
programmer for temporary storage or 
subroutine interrupt service linkage. The 
stack uses the "last-in, first-out" 
concept. The stack starts at the highest 
location reserved for it and expands 
linearly downward as items are added to 
the stack. 
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Stack pointer 

A general register used to keep track of 
the last location where data is entered 
into the stack. 

Storage device 

A general term for any device capable of 
retaining information. 

Subconditionals 

Directives that indicate: 

1. assembly of an alternate body of code; 

2. assembly of a non-contiguous body of 
code within a conditional block; 

3. unconditional assembly of a body of 
code within a conditional block. 

Subpicture address 

Address of a set of display processor 
instructions which display text on a GT40 
(42,44). 

Suspend 

To temporarily halt execution of a task 
while another task of different priority 
runs. 

Swap 

The process of saving user memory in 
system device scratch blocks, reading in 
and executing a USR function, and then 
restoring the user code. 

Switch register 

A location in the CPU which can be loaded 
with a value by the operator by his 
setting switches on the computer console 
for each bit he wants to enter. 

Switches 

1. in a command string to the CSI a 
switch is a slash followed by an ASCII 
character which can be given a value 
by typing a colon after the character 
followed by an octal number or from 
1-3 ASCII characters. 

Symbols 

2. Two or three position mechanisms used 
for operating computer or devices. 

Names which can be assigned values or 
which can be used to indicate specific 
locations in a program. 

Symbol table 

An array which contains all defined 
symbols and the binary value associated 
with each one. Mnemonic operators, labels 
and user defined symbols are all placed in 
the symbol table. (Mnemonic operators 
stay in the table permanently.) 

System configuration 

See Configuration. 

System device 

A peripheral file-structured storage 

device on which the monitor resides. 
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System programs 

Time-critical job 

Transfer address 
Trap 


Truncation 
Two's complement 

Type-ahead 

Unary operation 
User-defined sybmbol 

Utility 

Vector 

Wild card operation 

Word-for-word transfer 


DEC-supplied programs which come in the 
basic software packages. These include 
editors, PIP, assemblers, compilers, 
loaders, etc. 

A job which demands response within a 
fixed time period. 

A program entry point. 

1. An automatic transfer of control to a 
prespecified routine that can be 
caused by software or hardware. The 
trap instruction is an example of a 
hardware implementation. 

2. A conditional jump to a known location 
performed automatically by hardware as 
a side effect to executing a processor 
instruction. The address location 
from which the jump is made is 
recorded. It is distinguished from an 
interrupt which is caused by an 
external event. 

The reduction of precision by ignoring one 
or more of the digits (not rounding off) . 

A number used to represent the negative of 
a given value in many computers. This 
number is formed from the given binary 
value by changing all Is to Os and all Os 
to Is, and then adding 1. 

The ability to type information at the 
console terminal and have it remembered by 
the system for later use. 

Operation affecting a single operand. 
Examples: negation, radix indicator. 

1. A label; 

2. A symbol defined by direct assignment. 

Any program which performs useful 
functions, i.e., PIP. 

Two words describing 1) where to go when 
external interrupt occurs, and 2) the 
contents of the processor status word when 
the interrupt is acknowledged. 

A shorthand method of transferring all 
files with the same name, extension, or 
both. 

A transfer in which no alteration of data 
is performed. 
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Wor< 3s In the PDP-11 a 16-bit unit of data which 

may be stored in an addressable location. 

Write-lock condition The condition of a device that is 

protected against any transfers which 

would write information to it. 

Zero To initialize a device (e.g., DECtape, 

cassette) so that it contains no 

information. 
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Abbreviating command names (BATCH) 
12-3 

Abort entry point, 9-46, H-4 
Absolute, 5-3 

and relocatable program sections 
6-4 

block numbers, 4-21, 1-2 
expression, 5-18, C-5 
load address, 6-1 
load module, 6-5 
mode, 5-24 
quantities, 5-17 
section, 6-4 
starting block, 4-17 
Absolute Loader, 6-5 
Absolute sectors, reading and 
writing, 9-85, H-13.2 
Accessing, 

general registers, 8-9 
internal registers, 8-10 
Add two INTEGER*4 values, 0-88 
Additional and reference 
material, xxiii 
Address mode syntax, C-5 
Address specifier, M-2 
Addressed location, 8-8 
Addresses, vector, 9-6 
Addressing modes, 5-20 
Advance command, 3-17 
AJFLT function, 0-21 
Allocating, 

blocks for files, 4-11 
character string variables, 0-19 
extra words, 4-18 
memory for a queue, 9-66 
system resources, 2-16 
words, 2-36 

Alphabetize switch, 6-18 
Alphabetized load map, 6-19 
Alphanumeric representation, 1-2 
ALTMODE, 3-2 
Argument, 3-4 
block, 9-3 
CSECT, M-3 
dummy, 5-67 
iteration, 3-8 
list, 9-5 
list pointer, 9-2 
negative line, 3-7 
numeric, 3-6 
numerical, 9-4 
positive, 3-7 
substitution, 5-72 
Arguments, 9-2 
EDIT, 3-4 

indefinite repeat, 5-72 
missing, 5-66 
number of, 5-66 
real, 5-63 
symbolic, 5-37 


Arguments (cont.), 

to Macro calls and definitions 
5-62 
ASCII, 

character set, C-l, C-4 
code, 0-18 

conversion of one or two 
characters, 5-40 
files, 3-1 
format, 2-3 

input and output, 8-20 
to Radix-50 conversion, 0-105 
.ASCII directive, 5-41 
.ASCIZ directive, 5-42 
.ASECT directive, 5-53, 6-4, 6-6 
.ASECTs, H-3 

ASEMBL (8K assembler), 1-4, 11-1 
calling and using, 11-1 
error messages, 11-7 
file specifications, 11-2 
Assembler, 1-2, 8-4 
ASEMBL, 11-1 
MACRO, 5-1, 12-29 
output, 5-19 

Assembler directives, 5-3, 5-27, 
C-19 

.ASCII, 5-41 
.ASCIZ, 5-42 
.ASECT, 5-53 
.BLKB, 5-47 
.BLKW, 5-47 
.BYTE, 5-38 
.CSECT, 5-53 
.DSABL, 5-36 
.ENABL, 5-36 
.END, 5-50 
.ENDM, 5-60 
.EOT, 5-51 
.ERROR, 5-70 
.EVEN, 5-46 
.FLT2, 5-48 
.FLT4, 5-48 
.GLOBL, 5-54 
.IDENT, 5-36 
.IFF, 5-57 
.IFT, 5-57 
.IFTF, 5-57 
.IRP, 5-71 
.IRPC, 5-72 
.LIMIT, 5-51 
.LIST, 5-27 
.MACRO, 5-60 
.MCALL, 5-74 
.MEXIT, 5-61 
.NARG, 5-68 
.NCHR, 5-68 
.NLIST, 5-27 
.NTYPE, 5-69 
.ODD, 5-46 


INDEX-1 


January 1976 





Assembler directives (cont.), 
.PAGE, 5-36 
.PRINT, 5-71 
.RADIX, 5-44 
.RAD50, 5-43 
.REPT, 5-73 
.SBTTL, 5-34 
.TITLE, 5-34 
.WORD, 5-39 

Assembling graphics programs, N-16 
Assembly instructions, N-24 
Assembly, 

language completion routine, 
0-100 

language display support, N-l 
language routines, 0-5 
language statement, 5-2 
listing, 8-1 

listing table of contents, 5-35 
location counter, 5-14 
pass, 5-14 

source listing showing local 
symbol blocks, 5-15 
ASSIGN command, 2-18 
Asterisk, 

data line indicator, 12-38 
wild-card, 4-1, 12-7 
Asynchronous completion routines, 
9-13 

Autodecrement mode, 5-23 
Autodecrement deferred mode, 5-23 
Autoincrement mode, 5-21 
Autoincrement deferred mode, 5-22 
Automatic generation of local 
symbols, 5-13 

Automatic relocation facility, 8-4 
Automatically created symbols 
within user-defined Macros, 
5-66 


Backslash, 8-7 
Backup storage device, 6-10 
Back-arrow, 8-8 
Back space, H-ll, 0-72 
Bad block files, 4-2 
Bad block scan, 4-21 
Bad entry, 8-2, 8-26 
Base address, 5-25, 8-4 
Base command, 2-29 
Base segment, N-2 
$BASIC command, 12-13 
BASIC/GT subroutine structure, N-20 
BASIC/RT-11, 1-1, 1-5 
commands, F-3 
error messages, F-6 
function errors, F-9 
functions, F-5 
language, F-l 
language summary, F-l 
statements, F-l 
string functions, F-5 


BATCH, 1-5, 12-1 

character set, 12-8 
command field switches, 12-3 
command fields, 12-2 
command summary, B-17 
commands, 12-12, 12-36 
comment fields, 12-8 
control statement format, 12-2 
device names, 12-6 
differences between RT-11 BATCH 
and RSX-llD BATCH, 12-52 
error messages, 12-53 
example, 12-36 
filename extensions, 12-7 
file specifications, 12-6 
files, 12-10 

hardware requirements, 12-1 
operating procedures, 12-45 
operator directives, 12-50 
punched card programs, 12-44 
RT-11 mode, 12-38 
rules and conventions, 12-11 
software requirements, 12-2 
specification field switches, 12 
specification fields, 12-5 
switch summary, B-14 
wild card construction, 12-7 
BATCH commands, 

$BASIC, 12-13 
$CALL, 12-14 
$CHAIN, 12-15 
$C0PY, 12-16 
$CREATE, 12-18 
$DATA, 12-19 
$DELETE, 12-20 
$DIRECTORY, 12-20 
$DISMOUNT, 12-21 
$E0D, 12-22 
$EOJ, 12-23 
$F0RTRAN, 12-23 
$JOB, 12-25 
$LIBRARY, 12-27 
$LINK, 12-27 
$MACR0, 12-29 
$MESSAGE, 12-31 
$MOUNT, 12-32 
$PRINT, 12-34 
$ RT11, 12-35 
$RUN, 12-35 
$SEQUENCE, 12-36 
Beginning command, 3-16 
Binary, 
code, 1-2 

object module, 8-4 
operators, 5-8, 5-18 
output, 1-2 
radix, 5-17, 5-45 
Bit patterns, 1-3, 8-24 
search, 8-10 
.BLANK, N-3 
Blank COMMON, 6-14 
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Blank, 

extension filename, 2-7 
fields, 9-110 
lines, 5-2 

.BLKB directive, 5-47 
.BLKW directive, 5-47 
Blocks, 2-10 
control, 6-1 
device, 9-5 
EMT arguments, 9-5 
lengths, 4-4 
256-word, 2-32 
Block numbers, H-9 
absolute, 1-2 
physical, 1-2 

Block-replaceable devices, 2-7, 
2-36, 4-14 

Boot operation, 4-20 
Bootable magtape, 4-5 
Bootstrap, 

copy operation, 4-20 
file, 4-19 
manual, 2-2 

Bootstrapping the system, 4-20 
Bottom address switch, 6-18 
Branch, 

address, 5-26 

instruction addressing, 5-26 
instructions, 5-27, C-13 
Breakpoints, 8-11, 8-21 
table, 8-10, 8-13 
Buffer, 

flag, N-7, N-ll 
macro, 3-10 
save, 3-10 
structure, N-7 
text, 3-2, 3-21 
Building, 

a memory image, 2-28 
VTLIB.OBJ, N-26 
Byte, 8-7 

offset, 5-27 
BYTE command, M-3 

BYTE directive, 5-38 


Calculating offsets, 8-17 
$CALL command, 12-14 
Calling and using, 

ASEMBL, 11-1 
DUMP, 1-1 
EDIT, 3-1 
EXPAND, 10-2 
FILEX, J-l 
LIBR, 7-1 
LINK, 6-2 
MACRO, 5-74 
ODT, 8-1 
PATCH, L-l 
PATCHO, M-l 
PIP, 4-1 
SRCCOM, K-l 

Calling SYSLIB subprograms, 0-3 


Calls or branches to overlay 
segments, 6-13 

Cancel scheduling requests, 0-36 
Card, 

deck, 12-45 
input, 12-46 
Card codes, 2-24, H-6 
conversion table, H-25 
Card reader handler, H-6, 12-46 
Carriage control, 0-33 
Carry bit, 9-13 
Cassette, 

handler functions, 0-72 
rewind button, 4-7 
sequence number, 4-7 
Cassette special functions, H-12 
last block, H-12 
last file, H-12 
next block, H-12 
next file, H-12 
rewind, H-12 
write file gap, H-13 
Cassettes and magtapes, 

end-of-file detection, H-13 
initializing, 4-13 
legal operations, 4-5 
Cathode ray tube, N-l 
.CDFN request, 9-26 
Centralized queue management 
system, 9-65 
CHAIN bit, 9-8 
$CHAIN command, 12-15 
.CHAIN request, 9-27 
CHAIN subroutine, 0-22 
Chaining, 0-105 
Change command, 3-22 
Changing, 

device handler characteristics, 
2-23 

monitors, 2-2.1 
stack size, 2-36 
Channel, 9-41 

allocation, 0-34, 0-46 
assignment, 0-99 
data, 9-78 
deactivation, 0-103 
number, 9-5, 0-47 
returned to pool, 0-45 
status, 0-39, 0-65 
status word, 9-13, 9-41, 9-78 
Channel-oriented operations, 0-9, 
0-17 

Channels, 9-35 
Chapter summary, xxi 
Character, 

deletion, 9-94 
substitution, 5-72 
transfer, 9-93 

Character- and line-oriented 
command properties, 3-6 
Character-oriented commands, 3-6 
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Character set, 5-5, 12-8, 12-9 
ASCII, C-4 
Radix-50, C-3 
Character string, 
comparison, 0-108 
functions, 0-13, 0-18 
shortening, 0-18 
Character transfer, 

console terminal to user program 
0-79 

user program to console terminal 
0-81, 0-102 

Character translation, 0-116 
Character verification, 0-119 
Characters, 
illegal, 5-7 
legal, 5-5 
operator, 5-8 
optional, 2-14 
prompting, 2-4 
special, 5-64 

upper-/lower-case, 3-27, 0-80 
.CHC0PY request, 9-28 
Checking channel status, 9-99 
Checksum, 4-9, M-4, M-5 
.CLEAR, N-4 

Clearing breakpoints, restarting 
0DT, 8-2 
Clock, 2-17 

frequency, 9-52 
rate, 2-17, 9-52 
ticks, 9-51 
CLOSE command, 2-20 
CLOSE handler function, H-9 
.CLOSE request, 9-30 
CL0SEC subroutine, 0-23 
Closed location, 8-6 
Closing a channel, 0-23 
.CMKT request, 9-31 
•CNTXSW request, 9-32 
Code, 

binary, 1-2 
modifications, L-l 
object, 1-2 
source, 1-2 
Combining 
files, 4-9 

library switch functions, 7-11 
Command and Switch Summaries, B-l 
Command, 

arguments (EDIT), 3-5, B-5 
continuation switch, 7-3 
decoder, 8-20 
execution routine, 8-21 
field, 12-2 

field switches, 12-3, 12-6 
interpretation services, 9-1 
mode, 3-2 
repetition, 3-8 
string format, 2-10 
string interpreter (SYSLIB), 

0-37 

strings, 3-5, 6-2 
structure (EDIT), 3-3 
January 1976 


Command (cont.), 
switches, 4-1, K-2 
syntax (LIBR), 7-2 
Command String Interpreter, 2-7, 
2-10, 6-3, 9-33, L-2 
Command summary, 

BATCH, B-17 
EDIT, B-5 

r Keyboard monitor, B-l 
0DT, B-12 
- PATCH, B-20 
PATCH0, B-21 
Commands, 

and functions, 8-5 
BASIC/RT-11, F-3 
BATCH, see BATCH commands 
character-oriented, 3-6 
control, 3-2 
display editor, 3-4 
edit control, 3-2 
input/output, 3-3, 3-10 
keyboard, 2-14 
line-oriented, 3-6 
PATCH, L-2 

pointer relocation, 3-16 
search, 3-18 

text modification, 3-4, 3-20 
utility, 3-4, 3-24 
Commands to allocate system 
resources, 2-16 
ASSIGN, 2-18 
CLOSE, 2-20 
DATE, 2-16 
INITIALIZE, 2-18 
LOAD, 2-20 
SET, 2-23 
TIME, 2-17 
UNLOAD, 2-23 

Commands to control terminal I/O 
2-15 

GT OFF, 2-16 
GT ON, 2-15 

Commands to manipulate memory 
images, 2-28 
Base, 2-29 
Deposit, 2-30 
Examine, 2-30 
GET, 2-28 
SAVE, 2-31 

Commands used only in a F/B 
environment, 2-35 
FRUN, 2-36, 

RSUME, 2-38 
SUSPEND, 2-37 
Command field, 5-2, 5-4 
Comments, 12-8, 12-43 
Common blocks, 6-14 
Comparing 

character strings, 0-108 
two INTEGER*4 values, 0-89 
Compiler, BATCH, 12-1, 12-47 
Completion functions, 9-14 
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Completion routines, 2-37, 2-38, 
9-13, 9-49, 9-60, 9-90, 0-15 
0-16 

Component sizes, 2-9 
Components, 

system hardware, 1-5 
system software, 1-3 
Compress operation, 4-19 
Compressing 

directories, 4-19 
files, 4-19 

CONCAT subroutine, 0-24 
Concatenation, 5-67 
Concatenating specified strings, 
0-107 

Condition codes, 8-10, 9-21.1 
Conditional, 

assembly directives, 5-55 
block, 5-55 

transfers of control, 12-40 
Configuration word, 9-11, 9-52, 
9-85 

Confirming file transfers, 4-10 
Console, 

normal mode, 9-94 
special mode, 9-94 
terminal, 3-1, 3-27 
terminal control and status 
registers, 9-12 
terminal input modes, 

Constant register, 8-5, 

Context switch, 9-32 
Contiguous 
area, 9-13 

file, 7-12, 9-13, J-7 
Continuation character, 
Continuation lines, 5-2 
Continue switch, 6-20 
Control, 

block, 6-1 no/io 

characters in RT-11 mode, 12-4z 

commands, 3-2 
parameters, 6-6 
section names, 6-1 
statement format, 12-2 
Control section, 
named, 6-4 
unnamed, 6-4 

Controlling terminal I/O, 2-15 
Conventions and restrictions, 0-2 
Conventions and rules, 12-11 
Conventions, system, 2-3 
Conversion (SYSLIB), 

ASCII to Radix-50, 0-105 
INTEGER*2 to INTEGER*4, 0-92 
INTEGER*4 to INTEGER*2, 0-47 
INTEGER*4 to REAL*4, 0-21, 0-31 
INTEGER*4 to REAL*8, 0-27, 0-41 
Radix-50 to ASCII, 0-109 
REAL*4 to INTEGER*4, 0-88 
REAL*8 to INTEGER*4, 0-90 
Conversion, Octal-Decimal, C-25 
Converting VI Macro calls to V2, 
9-108 


0-80 

8-10, 8-16 


12-2 


Copy, 

routine, 0-109 
substring, 0-112 
$C0PY command, 12-16 
Copy operations, 4-9 
errors, 4-9.1 
multiple, 4-11 
Copying, 

files with the current date, 4-30 
multiple cassette files, 4-8 
system files, 4-10 
Co-resident overlay routines, 6-22 
Core memory, 1-1 

Correct and incorrect macro calls, 
9-3 

Correcting and updating object 
modules, M-l 
CR (card reader), H-6 
$CREATE command, 12-18 
Creating, 

a library file, 7-4 
a new file, 4-6 

RT-11 mode BATCH programs, 12-39 
CREF, 1-4 

error messages, 5-86 
listing output, 5-81, 5-82, 

5-83 

specification switches, 5-76 
switches, 5-78, C-24 
Cross reference, 

control sections, 5-78 
errors, 5-78 
listings, 1-4, 12-3 
MACRO symbols, 5-78 
permanent symbols, 5-78 
register-equate symbols, 5-78 
table generation, 5-78 
CSECT argument, M-3 
.CSECT directive, 5-53, 6-4 
CSECT, 7-13 
CSI, 

error messages, 9-35 
general mode, 9-34 
special mode, 9-36 
switch separators, 9-38 
.CSIGEN request, 9-33 
.CSISPC request, 9-36 
.CSTAT request, 9-41 
CTRL A, 2-12 


CTRL B, 
CTRL C, 
CTRL E, 
CTRL F, 
CTRL 0, 
CTRL 0 


2-12 

2 - 12 , 

2-12 

2-12 

2-13, 

reset, 


3-2, 8-3, H-5 


3-3, H-5 
0-106 


CTRL Q, 2-13 

CTRL S, 2-13 

CTRL U, 2-13, 3-3, 8-4 

CTRL X, 3-3 

CTRL Z, 2-13, H-5 

Current, 

location counter, 5-3, 5-14 
location pointer, 3-6 
subpicture tag, N-14 
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Cursor, 3-29, N-2 
CVTTIM subroutine, 0-25 


Data, 

format, 2-3, J-l 
input, 12-19 
length, 9-78 

storage directives, 5-37 
transfer functions, 0 - 7 , 0 - 8 , 
0-9 

transfer requests, 9-15 
$DATA command, 12-19 
DATE command, 2-16 
•DATE request, 9-20 
De-activating a channel, 9-65 
Debugger, 1-2 
Debugging, 
process, 1-2 
tool, 1-3 
DEC command, M-5 

DEC 026/029 card conversion table 
H—23 
Decimal, 

number, 5-17 
radix, 5-17, 5-45 
DECsystem-10, 

DECtape, J-l 

file-structured device, J -3 
DECtape, 

DECsystem-10, J-l 
PDP-11 DOS/BATCH, J-l 
RSTS-11, J-l 
Default, 

devices, 12-6 
extensions, 9-34 
FORTRAN library switch, 6-20 
stack, 9-7 

switches, BATCH command field, 
12-3 

Defining N0TAG, N-19 
Delete 

command, 3-21 
global switch, 7-7 
input files, 12-3 
operation, 4-13 
switch, 7-6 

$DELETE command, 12-20 
DELETE handler function, H -8 
.DELETE request, 9-42 
Deleted files, 
on cassette, 4-6 
on magtape, 4-6 
Deleting files, 4-13 

from DOS/BATCH (RSTS) DEC- 
tajies, J-7 

Delimiting characters, 3-25 
separating and, 5-6 
Deposit command, 2-30 
Description of graphics macros, N-3 
Destination device, 4-9 


Device, 

and file specifications, 0-10 
assignment, 12-6 
block, 9-5 

block replaceable, 2-7 
designation, 3-12 
dismounting, 12-21 
file-structured, 2-7, J-l 
mounting, 12-32 
name, logical, 2-5 
name, physical, 2-19, 9-5 
nonfile-structured, 2-7, 6-21 
nonRT—11 directory- 
structured, 2-7 
ownership, 2-21 

random access, 2-7, 4-8.1, 6-1 
RT-11 directory-structured, 2-7 
sequential-access, 2-7 
size, 9-46 
specification, 2-11 
Device-dependent functions, 0-72 
status, 0-42 

Device Handlers, 2-8, 9-50, H-3 1 
BATCH, 12-46 

differences between VI and V2, 
H-4 

foreground programming and, H-l 
loading, 9-50 
loading SYSLIB, 0-44 
making resident, H-3.1 
user-written, H-4 
Device-dependent functions, 9-85 
Device names, 

logical, 2-5, 12-6 
permanent, 2-5 
physical, 2-4, 12-6 
.DEVICE request, 9-44 
Device structures, 2-7 
DEVICE subroutine, 0-26 
DHALT display halt instructions, 
N-14 

Differences between RT -11 and 
RSX-11D BATCH, 12-52, 12-53 
Differences between VI and V2 de¬ 
vice handlers, H-4 
abort entry point, H-4 
entry conditions, H-4 
header words, H-4 
interrupt handling, H-4 
Differences between versions, 
xxii 

Direct assignment statement, 5-10 
5—14 

conventions, 5-11 
format, 5-10 
Directives, 

assembler, see assembler direc¬ 
tives 

BATCH, 12-49, 12-50 
conditional assembly, 5-55 
data storage, 5-37 
immediate conditional, 5-58 
listing control, 5-27 
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Directives (cont.), 

Macro, 5-60 

not available in ASEMBL, 11-2 
PAL-11R, 5-59 
PAL-11S, 5-59 
program boundaries, 5-51 
program section, 5-51 
terminating, 5-50 
Directory, 

access motion and code consoli¬ 
dation, 9-79 

initialization operation, 4-18 
list operations, 4-15 
listing of magtapes, 4-7 
segments, 4-18, 4-19 
Directories, compressing, 4-19 
Disk, DOS/BATCH, J-l 
Diskette, H-13.2 

handler function, 0-72 
Display, 

extended instructions, N-13 
file handler, N-l, N-2 
file structure, N-17 
handler macro calls, N-16 
hardware, 3-29 
interrupt vectors, N-5 
processor, N-l 
program counter, N-14 
screen, 3-28 
status register, N-14 
status words, N-8 
stop instruction, N-2, N-18 
stop interrupt handler, N-14 
X register, N-14 
Y register, N-14 
Display editor, 3-28 
format, 3-29 
using the, 3-29 
Display processor, N-l 
management, N-2 
mnemonics, N-16, N-23 
Divide two INTEGER*4 values, 0-91 
DJFLT function, 0-27 
DJSR subroutine call instruction, 
N-13 

DNAME load name register instruc¬ 
tion, N-15 

Documentation conventions, xxiv 
Dollar sign, 

in BATCH control statement, 12-2 
in data, 12-4 
DOS/BATCH disk, J-l 
Double ALTMODE, 3-29 
Double-buffered I/O, 9-105 
Double Operand Instructions, C-8 
Double precision values, 0-27, 0-41 
Double Register-Destination, C -17 
DRET subroutine return instruction, 
N-14 

•DSABL directive, 5-36 
DSTAT display status instruction, 
N-14 

•DSTATUS request, 9-45 


Dummy, 

argument, 5-67 
argument list, 5-60 
file, 4-6 
names, 4-14 
DUMP, 1-5, 1-1 

calling and using, 1-1 
error messages, 1-5 
switches, 1-2, B-18 
DUMP command, M-4 


E command, L-3 
Edge flag, N-12 
Edit Backup command, 3-11 
Edit Console command, 3-29 
Edit Display command, 3-30 
Edit Lower command, 3-27 
Edit Read command, 3-10 
Edit Upper command, 3-27 
Edit Version command, 3-27 
Edit Write command, 3-11 
Editor (EDIT), 1-2, 3-1 
arguments, 3-4, 3-5, B-5 
calling and using, 3-1 
command structure, 3-3 
control commands, 3-2 
display, 3-28 
editing commands, 3-10 
error messages, 3-33 
example, 3-32 

immediate mode commands, 3-31, 
B-8 

input/output commands, 3-10, B-5 
key commands, 3-2, B-8 
modes of operation, 3-2 
pointer relocation commands, 
3-16, B-6 

search commands, 3-18, B-6 
text modification, 3-20 
utility commands, 3-24, B-7 
Effective address search, 8-15 
Empty entry, 9-13, 9-43 
EMT, 

and TRAP addressing, 5-27 
argument blocks, 9-5 
error code, 9-8 
instruction, 9-2 
•ENABL directive, 5-36 
.END directive, 5-50 
End File command, 3-15 
End of job (BATCH), 12-23 
.ENDM directive, 5-60 
.ENDM statement, 5-74 
•ENDR statement, 5-74 
ENTER handler function, H-8 
•ENTER request, 9-47 
Entering command information, 2-10 
Entry conditions, H-4 
Entry point, 5-10, 5-55, 6-7, 

6-13, 9-46 

table, 7-5, 7-12, 7-13 
Entry symbol, 6-5 
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$EOD command, 12-22 
$EOJ command, 12-23 
.EOT directive, 5-51 
Error, 

code, 9-35 
returns, 9-99 
.ERROR directive, 5-70 
Error halt bit, 9-8 
Error messages, 

ASEMBL, 11-7 
BASIC/RT-11, F-6 
BATCH, 12-53 
CREF, 5-86 
DUMP, 1-5 
EDIT, 3-33 
keyboard, 9-40 
MACRO, 5-84 
monitor, 2-38 
PATCH, L-7 
PATCHO, M-7 
PIP, 4-24 

Evaluation of an expression, 5-18 
Even byte, 9-6 
.EVEN directive, 5-46 
Examine, change locations in the 
file, L-3 

Examine command, 2-30 
Examples, 

BATCH stream, 12-36 

calling a SYSLIB function, 0-4 

device handlers, H-14 

EDIT, 3-32 

MACRO line printer listing, 5-31 
page heading, 5-32 
PATCH, L-4 
PATCHO, M-6 
RT-11 mode, 12-43 
using GTON, N-28 
EX command, 3-16 
Exchange command, 3-23 
Exclamation point in BATCH comment, 
12-8 

Execute Macro command, 3-26 
Exit command, 3-15 
EXIT command, M-4 
Exit from PATCH, L-3 
.EXIT request, 9-49 
EXPAND, 1-4, 10-1 

calling and using, 10-2 
error messages, 10-6 
language, 10-1 
restrictions, 10-1 


Extensions, 3-12, K-2 
and filenames, 2-5 
filename (BATCH), 12-7 
External, 

expression, 5-18 
symbols, 5-10, 6-5 


Expression, 

C-5 


absolute. 

5-18, 

C-5 

external, 

5-18 


register, 

5-20, 

C-5 

relocatable, 5- 

18, 

Expressions 

, 5-18 



symbols and, 5-5 
Extend and delete operations, 4-13 
Extended display instructions, N-13 
Extending file lengths, 4-13 


F command, L-2 
Facilities, 

available only in RT-11 F/B, 1-8 
for input and output operations, 

9-1 

Fast listing, J-7 

Fatal monitor error messages, 2-39 
Fatal system boot error messages, 

2-38 

F/B programming and device han¬ 
dlers, H-l 

F/B programming in RT-11, Version 
2, H-l 

F/B system, background area, 2-9 

.FETCH request, 9-50 

Field, 

comment, 5-2, 5-4 
label, 5-2, 5-3 
operand, 5-4 
File, 

allocation scheme, 4-10 
ASCII, 3-1 
compressing, 4-19 
concatenation, 12-16 
deletion, 12-20, 0-40 
descriptor blocks, 9-37 
dummy, 4-6 
formats, J-l 
gap, 9-86, H-12 
length, 9-78 
linking, 12-28 
manipulation requests, 9-15 
manipulation services, 9-1 
memory image, 2-3, 4-9, L-l 
names and extensions, 2-5 
non-overlay, L-3 
overlay, L-l 
permanent, 9-13 
printing, 12-34 
relocatable image, 2-3 
replacement, 4-8.1 
sentinel, 4-4 

specifications (ASEMBL), 11-2, 
(BATCH), 12-6 
structure, 9-13, H-6 
temporary, 4-23, 12-7, 12-10, 12-15 
tentative, 9-13 
transfer, 4-1 

File-formatted devices, J-l 
File-oriented operations, 0-7 
File-structured RT-11 device, 2-7, 

J-l 

Filename, 3-12 

blank extensions, 2-7 
extensions, 2-6, 12-7 
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Filename (cont.), 
input, 4-1 
output, 4-1 
FILEX, 1-4, J-l 

calling and using, J-l 
error messages, J-8 
overview, J-l 
switch options, B-18, J-2 
Fill characters, 9-9 
Fill count, 9-9 
Find command, 3-19 
Fixed record length, H-6 
Floating point, 
exception, 9-84 
hardware, 5-47, 9-84 
numbers, 5-17, 5-48 
source double register, C-15 
.FLT2 directive, 5-48 
.FLT4 directive, 5-48 
Foreground/Background, 1-1 
terminal I/O, 2-13 
Foreground links, 6-6 
Format, 

ASCII, 2-3 
control, 5-5 

load image, 2-3, 6-2, 6-21 
memory image, 2-3 
object, 2-3 

of Entry Point Table, 7-13 
of library files, 7-12 
of programmed requests, 9-2 
relocatable image, 2-3 
register, 8-6 
statement, 5-2 
Formats, data, 2-3 
Formatted binary copy switch, 4-9 
Formatting, 

horizontal, 5-5 
vertical, 5-5 

Form feed character, 3-1, 3-12 
Forms of relocatable expressions, 
8-5 

$FORTRAN command, 12-23 
FORTRAN IV, 1-1, 1-5, G-l 
character set, G-2 
compiler error diagnostics, G-ll 
expression operators, G-3 
running a FORTRAN program in the 
foreground, G-l 
statements, G-4 

FORTRAN System Subroutine Library, 
see SYSLIB 
Forward space, H-ll 
Fragmented device, 9-13 
Free area, 4-11 
Free memory list, 2-9, 2-22 
FRUN command, 2-36 
FRUN /N option, 0-6 
FRUN processor, 9-7 
Function, 
code, 9-6 

control switches, C-23 


Function (cont.)/ 

switches, 5-76, 5-77 
types, 0-2 

FUNCTION subprograms, 0-3 
Functions, BASIC/RT-11, F-5 


General, 

address specification, 5-21 
file transfer program, J-l 
library file format, 7-12 
memory layout, 2-8 
registers, 5-11, 8-9 
GET command, 2-28 
Get command, 3-18 
GETSTR subroutine, 0-28 
Global symbol directory, 7-14 
Global symbol table, 6-1, 6-5 
Global symbols, 5-10, 5-55, 6-1, 
6-5, M-3 

Globals, unresolved, 6-1 
.GLOBL directive, 5-54 
GOTO statement, 12-41 
Graphics macro calls, summary, 
N-21 

Graphics programs, 

assembling and linking, N-16 
GT OFF, 2-15, 2-16, N-2 
GT ON, 2-15, 3-29, N-2 
GTIM subroutine, 0-29 
.GTIM request, 9-51 
GTJB subroutine, 0-29 
.GTJB request, 9-52 


HALT instructions, 2-41 
Handler functions, H-8 
CLOSE, H-9 
DELETE, H-8 
ENTER, H-8 
LOOKUP, H-8 
READ/WRITE, H-9 
Handler size, 9-46 
Handlers, 2-36 

device, 2-8, 12-46, H-l, H-3.1 
display file, N-2 
functions, 0-72 
internal display file, N-2 
removing from memory, 9-74 
unloading, 12-48 
Hardware bootstrap, 4-20 
Hardware, 

configuration, 2-1 
display, 3-29 
memory protection, 9-6 
mode, H-6, H-13.1 
requirements, 12-1 
Header words, H-4 
HELP command, M-5 
.HERR request, 9-53 
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High, 

address, 2-32 
level languages, 1-3 
memory address, 9-8 
order time of day, 9-52 
Horizontal formatting, 5-5 
.HRESET request, 9-55 


IADDR function, 0-30 
IAJFLT function, 0-31 
IASIGN function, 0-32 
ICDFN function, 0-34 
ICHCPY function, 0-35 
ICMKT function, 0-36 
ICSI function, 0-37 
ICSTAT function, 0-39 
IDELET function, 0-40 
.IDENT directive, 5-36 
Identification messages, 2-2 
IDJFLT function, 0-41 
IDSTAT function, 0-42 
IENTER function, 0-43 
IF statement, 12-40 
IFETCH function, 0-44 
.IFF Directive, 5-57 
IFREEC function, 0-45 
•IFT Directive, 5-57 
.IFTF Directive, 5-57 
IGETC function, 0-46 
IJCVT function, 0-47 
Illegal characters, 5-7, 8-26 
ILUN function, 0-47 


Insert command, 3-20 
INSERT subroutine, 0-49 
Inserting modules into a library, 
7-5 

•INSRT, N-5 
Instruction, 

EMT, 9-2 
mnemonic, 5-3 
offset, 8-17 
Instructions, C-6 
branch, C-13 
double operand, C-8 
operate, C-ll 
rotate/shift, C-9 
single operand, C-8 
trap, C-12 

INTEGER*4 support functions, 0-12 
0-13, 0-17 

Integer value of the word, 0-76 
.INTEN request, 9-21, H-2, H-4 
Interchange words of INTEGER*4 
value, 0-92 
Internal, 

buffers, 3-1 
Macro buffer, 3-26 
registers, 8-10 
subpicture stack, N-14 
symbol directory, 7-14 
symbolic names, 5-53 
symbols, 5-10 
tables, 10-1 
Interrupt, 

enable bit, 9-44 


Image mode transfer, 4-9 
Immediate conditional directive 
5-58 

Immediate mode, 1-3, 3-2, 3-4, 
3-30, 5-24, 9-3 
commands, 3-31, B-8 
Important memory areas, 9-6 
Include switch, 6-20 
Inclusive directory, 4-5 
Incrementing values of variable 
12-40 


handling, H-4, N-2 
level (issuing programmed 
requests), H-2 
priorities, H-l 
priority level, 8-10 
Service Routine, H-2, H-3, H-5 
0-50 

vector, H-l, H-3 
INTSET function, 0-50 
Invalid punch combinations, H-6 
I/O control at terminal (BATCH), 


Indefinite repeat, 
arguments, 5-72 
block, 5-71, 5-72 
Index Mode, 5-23, 5-25 
Index Deferred Mode, 5-23 
INDEX subroutine, 0-48 
Individual module name, 7-2 
Inhibit TT wait bit, 9-8 


12-42 

I/O count, 9-78 
exit routine, 
vector, 9-33 
IPEEK function, 
IP0KE function, 
IQSET function, 

IRAD50 function. 


INITIALIZE command, 2-18 IRCVD functions. 

Initializing cassettes and magtapes,IREAD functions. 


4-13 

Input and output, 3-3, 6-5 


IRENAM function, 
IREOPN function. 


9-11 

0-52 

0-52 

0-53 

0-54 

0-55 

0-58 

0-63 

0-64 


commands (Editor), 3-10, B-5 
Input, 

filenames, 4-1 
list, 2-11 
ring buffer, H-6 
source filename, 1-1 
SYSLIB, 0-58 
to RT-11 BATCH, 12-2 
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•IRP and .IRPC example 
.IRP directive, 5-71 
.IRPC directive, 5-72 
ISAVES function, 0-65 
ISCHED function, 0-66 
ISC0MP function, 0-108 
ISDAT functions, 0-68 
ISLEEP function, 0-71 
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ISPFN functions, 0-72 
ISPY function, 0-76 
Issuing programmed requests at the 
interrupt level, H-2 
Iteration argument, 3-8 
loops, 3-9 

ITIMER function, 0-77 
ITLOCK function, 0-79 
ITTINR function, 0-79 
ITTOUR function, 0-81, 0-102 
ITWAIT function, 0-82 
IUNTIL function, 0-83 
IVERIF function, 0-120 
IWAIT function, 0-84 
IWRITE functions, 0-84 


JADD function, 0-88 
JAFIX function, 0-88 
JCMP function, 0-89 
JDFIX function, 0-90 
JDIV function, 0-91 
JICVT function, 0-92 
JJCVT function, 0-92 
JMOV function, 0-93 
JMUL function, 0-94 
$JOB command, 12-25, 12-38 
Job 

execution resumed, 0-108 
header, 12-3 
parameters, 0-29 

Job Status Word, 2-32, 2-35, 9-7, 
9-94, H-3 

JSUB function, 0-95 
JTIME subroutine, 0-96 
Jump command, 3-17 
Jumps, 6-13 


Key commands, Editor, 3-2, B-8 
Key, LINE FEED, 8-7 
Keyboard, 

commands, 2-14 
communication (KMON), 2-11 
error messages, 9-40 
monitor (KMON), 2-7.1 
Keyboard Monitor (KMON), 2-7.1 
command summary, B-l 
special function keys, B-3 
Kill command, 3-22 


Label field, 5-2, 5-3 
Labels in RT-11 mode, 12-39 
Language summary, BASIC/RT-11, F-l 
Last block, H-12 
Last file, H-12 
LDA format, 6-2 
switch, 6-21 
Legal 

argument delimiters, 5-63 
characters, 5-5 


Legal (cont.) 

operations involving cassette 
or magtape, 4-5 

separating characters, 5-6, 5-67 
wild card, 4-2 
LEN function, 0-97 
Length, string, 0-97 
LET statement (BATCH), 12-40 
Librarian (LIBR), 1-2, 1-3, 1-4, 
7-1 

calling and using, 7-1 
error messages, 7-14 
switch commands, 7-2, 7-3, B-12 
Library 

BATCH default, 12-4 
directory, 7-1 
end trailer, 7-14 
header, 7-1, 7-12, 7-13 
processing, 7-14 
searches, 6-17 
$LIBRARY command, 12-27 
Library files, 6-8 
creation, 7-4 
directory listing, 7-9 
entry point table, 7-7 
format, 7-12 

inserting modules into, 7-5 
merging, 7-10 
SYSLIB, 0-6 

Library functions and subroutines, 
0-21 - 0-120 
Light pen, N-l 

status buffer, N-ll 
.LIMIT directive, 5-51 
Limitations, PATCHO, M-5 
Line- and character-oriented 
command properties, 3-6 
Line continuation character, 12-2 
Line deletion, 9-94 
formatting, 5-5 
oriented commands, 3-6 
printer overstriking capability, 
2-23 

LINE FEED key, 8-7 
Link and execute programs, 12-5 
$LINK command, 12-27 
Linkage map, temporary, 12-4 
Linker (LINK), 1-2, 1-4, 6-1, 7-14 
calling and using, 6-2 
error handling and messages, 

6-24 

input and output, 6-5 
load map, 8-2 

load map for background job, 6-9 
switches, 6-3, B-ll 
Linked 

list, 9-66 
program, 6-1 

Linking graphics programs, N-16 
Linking, relocation and, 5-19 
Linking with SYSLIB, 0-6 
List command, 3-14 
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LIST command, M-4 
.LIST directive, 5-27 
Listing, 

assembly, 8-1 
control directives, 5-27 
control switches, 5-76, C-23 
cross-reference, 1-4 
directories, J-6 
file, temporary, 12-4 
level count, 5-28 
the directory of a library file, 
7-9 

.LNKRT, N-5 
Load address, 2-36 
absolute, 6-1 
LOAD command, 2-20 
Load image format (.LDA), 2-3 
Load 

map, 1-2, 6-1, 6-7 
module, 1-2, 6-1, 6-5, 6-21 
Loading 

BATCH, 12-45 

device handlers, 9-50, 0-44 
device registers, 9-44 
memory image files, 2-33 
ODT with user program, 8-2 
root segment, 2-28 
Local symbol block, 5-13 
Local symbols, 5-12, 5-66 
automatic generation, 5-13 
Location, 

addressed, 8-8 
closed, 8-6 

counter arithmetic, 6-4.1 
counter control, 5-46 
open, 8-6 

Locations, opening, changing, and 
closing, 8-6 
.LOCK request, 9-56 
LOCK subroutine, 0-97, 0-119 
Locking USR in memory, 9-56 
Log device, 12-1 
Logical device name, 2-5 
BATCH, 12-6 
end-of-tape, 4-5 
identifier, 9-5 
names, 2-5, 2-18 
LOGICAL*1 array, 0-19 
LOOKUP function, 0-99 
LOOKUP handler function, H-8 
.LOOKUP request, 9-58 
Low and high addresses, 5-51 
-order priority, 8-19 
priority, 8-19 
Lower-case bit, 9-7 
Lower-case characters, 0-80 
Lowering the processor priority, 
H-2 

.LPEN, N-7 

L-shaped cursor, 3-29 
LSRA instruction, N-14 


Machine language, 1-2 
Macro, 

arguments, 5-7 
buffer, 3-10 
call, 5-3, 9-2 
call operator, 5-3 
definition, 5-60 
definition formatting, 5-61 
expansion, 9-24 
free source code, 10-1 
libraries, 5-74 
nesting, 5-63 
recursive, 10-6 
references, 10-1 
Macro assembler, 1-1, 1-3, 5-1 
calling and using, 5-74 
character code, C-l 
directives, 5-60 
error messages, 5-84 
features, 5-1 
instructions, C-l 

program section capabilities, 5-10 
source code, 5-80, 5-81 
source statements, 5-2 
special characters, C-5 
switches, 5-76, C-23 
symbol table, 5-9 
symbols, 5-9 
Macro calls, 

requiring no conversion, 9-108 
which may be converted, 9-108 
Macro command, 3-10, 3-25 
$MACRO command, 12-29 
MACRO used with SYSLIB, 0-3 
.MACRO directive, 5-60 
Magtape handler function, 0-72 
Magtape special functions, H-ll 
back space, H-ll 
forward space, H-ll 
off line, H-12 
rewind, H-ll 
write end-of-file, H-ll 
write with extended gap, H-12 
Main file/subroutine structure, N-19 
Main line code, H-5 
Mainstream code, 9-87 
Making patches permanent, 2-28 
Manipulating memory images, 2-28 
Manual bootstraps, 2-2 
Mark time, 1-8 
requests, 9-31 
Mask limit, 8-15 
Masking, 8-10 
Matching areas, K-l 
Maximum file size, 9-12 
.MCALL directives, 5-74 
Memory block initialization, 8-16 
Memory 

allocation (SYSLIB), 0-43 
BATCH, 12-1 
core, 1-1 

diagram, BASIC link with overlay 
regions, 6-11 
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Memory (cont.), 
examination, 0-52 
maps, 2-8, 8-4 
solid state, 1-1 
storage, 0-52 
usage, 3-9 
usage map, 6-6 
Memory image, L-l 

files, 2-3, 4-9, L-l 
format, 2-3 

Merging library files, 7-10 

$MESSAGE command, 12-31 

Message transfers under F/B, 0-68 

.MEXIT directive, 5-61 

.MFPS request, 9-21,1 

Minimum memory configurations, 5-1 

Miscellaneous operations, 0-14 

Miscellaneous services, 9-16 

Missing arguments, 5-66 

Mnemonics, 1-2 

Mode, 

absolute, 5-24 
autodecrement, 5-23 
autodecrement deferred, 5-23 
autoincrement, 5-21 
autoincrement deferred, 5-22 
command, 3-2 
general, 9-34 
hardware, H-6 

immediate, 1-3, 3-2, 3-4, 3-30, 
5-24 

index, 5-23, 5-25 
index deferred, 5-23 
instruction, 8-17 
Radix-50, 8-10 
register, 5-21 
register deferred, 5-21 
relative, 5-24 
relative branch, 8-9 
relative deferred, 5-25 
single instruction, 8-14, 8-17 
software, H-6 
source operand, 5-25 
special, 9-36 
text, 3-2, 3-20 
type-ahead, 2-14 
Modes, addressing, 5-20 
of operation (EDIT), 3-2 
Modify stack address, 6-21 
Modules, 1-2, 6-5 
absolute load, 6-5 
load, 6-1, 6-5, 6-21, 7-1 
object, 6-5, 6-16, 7-1, 7-13, 
7-14 

Monitor, 1-1, 2-1 

error messages, 2-38 
F/B, 1-6, 9-7 
HALTS, 2-41 

keyboard (KMON), 2-7.1 
memory protection map, 6-6 
Resident (RMON), 2-7.1, 9-7 
single-job, 1-6, 3-30, 9-7 


Monitor (cont.), 

software components, 2-7.1 
start procedure, 2-1 
version number, 9-11 
$MOUNT command, 12-32 
MOV instruction, 9-3 
Move INTEGER*4 variable, 0-93 
MRKT function, 0-100 
.MRKT request, 9-60 
MT/CT (Magtape (TU10/TM11) and 
Cassette (TA11), H-6 
general characteristics, H-6 
.MTPS request, 9-21.1 
Multiple, 

command lines, 2-14 
copy operations, 4-8, 4-11 
delimiters, 5-4 
GETS, 2-28 
labels, 5-3 
operands, 5-4, 5-38 
.QSET requests, 9-66 
Multiply-defined symbols, 5-13 
Multiply two INTEGER*4 values, 
0-94 

.MWAIT request, 9-62 
MWAIT subroutine, 0-101 


[n] construction, 4-11 
.NAME, N-9 
Name register , 
contents, N-14 

internal software register, N-15 
.NAME request, N-9 
Name value, N-7 
Names of devices, 

default (BATCH), 12-6 
Named 

COMMON, 6-14 
control sections, 6-4 
relocatable program sections, 
5-53, 5-54 

.NARG directive, 5-68 
.NCHR directive, 5-68 
Negative, 

line arguments, 3-7 
numbers, 5-17 
Nesting level, 5-63 
Next 

block, H-12 
file, H-12 
Next command, 3-14 
.NLIST , 5-27 
Nonfile-structured, 
delete, 4-5 
devices, 2-7, 6-21 
enter, 9-41 

lookup, 9-41, H-7, H-13.2 
Non-overlay file, L-3 
Non-time-critical job, 1-8 
Nonexistent symbol, 6-21 
NonRT-11 directory-structured 
devices, 2-7, 9-45 
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.NTYPE directive, 5-69 
Null specification, 11-2 
Number, C-18 
channel, 9-5 
decimal, 5-17 
monitor version, 9-11 
of arguments, 5-66 
update, 9-11 
Numbers, 

floating-point, 5-17, 5-48 
MACRO assembler, 5-17 
negative, 5-17 
octal, 5-17 
positive, 5-17 

software identification, xxii 
Numeric arguments, 3-6, 9-4 
passed as symbols, 5-64 
Numeric control, 5-47 


Object 

code, 1-2 
files, 6-5 

files, temporary, 12-4, 12-15 
format, 2-3 

modules, 5-19, 6-5, 6-16, 7-1, 
7-13, 7-14 

modules, relocatable, 8-1 
modules, starting point, 7-13 
output, 1-2 
.OBJ format, M-l 
Object Time System (OTS), 0-32 
Octal, 

channel number, 9-13 
numbers, 5-17 
radix, 5-17, 5-45 
Octal-Decimal conversions, C-25 
.ODD directive, 5-46 
Odd (high-order) byte, 9-6 
ODT 

(On-line debugging technique), 

1-5 

break routine, 8-23 
calling and using, 8-1 
command summary, B-12 
error detection, 8-25 
functional organization, 8-20 
linking ODT with the user 
program, 8-2 
priority bit, 8-2 
priority level, 8-19 
Offline, H-12 
Offset, 5-13, 5-25 
relative branch, 8-9 
relative branch instruction, 8-17 
Offset words, 9-11 
On-line debugging technique 
(ODT) - see ODT 
OPEN command, M-l 
Open file, 2-20 
Opening a byte address, L-3 
Opening, changing, and closing 
locations, 8-6 
Operand field, 5-4 


Operands, multiple, 5-38 
Operate Instructions, C-ll 
Operating procedures (BATCH), 12-45 
Operation, 

foreground/background, 1-1 
single-job, 1-1 
Operations on files, 4-2 
magtape and cassette, 4-4 
Operator 

action, wait for, 12-5 
characters, 5-8 

communication (directives), 12-49 
directives, 12-50 
field, 5-3 

message, 12-31, 12-42 
Operators, 

binary, 5-8, 5-18 
unary, 5-8, 5-45, 5-50 
Optional characters, 2-14 
Output, 

filenames, 4-1 
format, K-2 
list, 2-11 
ring buffer, H-6 


Packed image transfer, J-2 
Padding routine, 0-111 
Page, 3-1 

eject, 5-36, 5-61 
headings, 5-34 
.PAGE directive, 5-36 
PAL-11R directive, 5-59 
PAL-11S conditional assembly di¬ 
rective, 5-59* 

Parameter list, 2-31 
Parameters used as arguments, E-l 
Passing strings to subprograms, 0-20 
Passing switch information, 9-35, 
9-38 

PATCH utility program, 1-4, L-l 
commands, L-2 
command summary, B-20 
error messages, L-7 
examples, L-4 
PATCH, 

calling and using, L-l 
Patching, 

libraries, M-l 
new files, L-2 
OBJ files, M-l 
PATCHO, 1-4 
commands, M-l 
command summary, B-21 
error messages, M-7 
examples, M-6 
limitations, M-5 
run-time error messages, M-8 
PATCHO, 

calling and using, M-l 
PDP-11 DOS/BATCH DECtape, J-l 
Percent (%) character, 5-12, 12-40 
Peripheral Interchange Program 
(PIP), see PIP 
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Permanent, 

device names, 2-5 
files, 2-20, 9-13 
Permanent Symbol Table, 5-9 
Physical block numbers, 1-2 
Physical device, 2-19, 9-5 
names, 2-4, 12-6 

PIC (position independent code), 
8-18, 9-21 

PIP (Peripheral Interchange Pro¬ 
gram) , 1-4, 4-1 
copy operation, 4-9 
error messages, 4-24 
magtape or cassette operations, 
4-4 

switches, 4-2, 4-3 
switch summary, B-9 
warning messages, 4-25 
PIP, 

calling and using, 4-1 
POINT command, M-2 
Pointer location, 3-3 
Pointer relocation commands, 3-16 
for Editor, B-6 
Position command, 3-20 
Position independent code (PIC), 
8-18. 9-21 


Positive, 

arguments, 3-7, 4-5 
numbers, 5-17 

Power line synchronization feature, 
N-ll . , 

PR (High-Speed Paper Tape Reader), 

H-5 

$PRINT command, 12-34 

.PRINT directive, 5-71 

.PRINT request, 9-63 

PRINT subroutine, 0-102 

Printout formats, 8-5 

Priorities, Interrupt, H-l 

Priority, 9-21.1, C-18 

Proceed command, 8-12 

Proceed count, 8-13 

Processor Status, 8-1, 9-21.1, H-2 

Program Boundaries directive/ 5 51 

Program/ 

counter/ 5-20/ 8-8 
development aids, 1-2 
example (BATCH)/ 12-36 
execution/ 8-12 
runaway, 8-23 
section directives/ 5-51 
section names/ 5—53 
sections, absolute and relocat¬ 
able/ 6-4 

Program starting commands/ 2-33 
Rz 2-34 
REENTER, 2-35 
RUN, 2-33 
START, 2-34 


Programmed requests, 2-7.1, 9-1 
format, 9-2 
summary, E-l 
usage, 9-25 
Programming 

considerations, 8-20 
conventions, H-l 
errors, 1-3 

Prompting characters, 2-4 
.PROTECT request, 9-64, H-3 
Punched cards input, 12-2, 12-44 
.PURGE request, 9-65 
PURGE subroutine, 0-103 
Purging an inactive channel, 9—65 
PUTSTR subroutine, 0-103 


.QSET request, 9-65 
Quantities, absolute, 5-17 
Queue element, 9-61 
Queue size, 0-53 
Quoted-string literals, 0-21 


R50ASC subroutine, 0-104 
RAD50 function, 0-105 
.RADIX directive, 5-44 
Radix, 

binary, 5-17, 5-45 
control, 5-44 
decimal, 5-17, 5-45 
octal, 5-17, 5-45 
specification characters, 5-45 
Radix-50, 

character set, C-3 
conversion operations, 0-14, 
0-54, 0-104 
equivalents, C-4 
mode, 8-10 
notation, 5-36 
terminators, 8-11 
.RAD50 directive, 5-43 
Random-access, 

devices, 2-7, 4-8.1, 6-1, 9-45 
file capabilities, F-l 
R Command, 2-34 
RCHAIN subroutine, 0-105 
.RCTRLO request, 9-67 
RCTRLO subroutine, 0-106 
•RCVD request, 9-68 
.RCVDC request, 9-69 
.RCVDW request, 9-69 
READ command, 3-12 
Read functions, 0-58 
.READ request, 9-71 
.READC request, 9-72 
Reading an ASCII record, 0-28 
.READW request, 9-73 
READ/WRITE handler function, H-9 
Real arguments, 5-63 
Re-assembling, 1-3 
Rebooting the system, 4-19 
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Receive data functions, 0-55 
Receiving data, 9-68 
Reclaiming memory, 2-22 
Reconfiguration, 1-7 
Record, H-9 

Recovering files, 4-14 
Recovery from Bad Blocks, 4-21 
Recovery procedures during output 
operations, 4-8 

Recurring coding sequence, 5-60 
Recursive macros, 10-2 
Reducing disk fragmentation, 4-12 
Re-editing, 1-3 
Reenter bit, 2-35, 9-7 
REENTER command, 2-35, 3-2 
Reference line, K-3 
.REGDEF, macro call, 9-22 
Region number, 6-13 
Region, overlay, 6-10, 6-14 
Register Deferred Mode, 5-21 
Register, 

destination, C-14 
expression, 5-20, C-5 
mnemonic, 9-3 
mode, 5-21 
symbols, 5-11, 5-12 
Register-Offset, C-14 
Registers, 

console terminal control and 
status, 9-12 
constant, 8-16 
relocation, L-l 

Reinitializing monitor tables, 

4-20 

Relative, 

branch, 8-15 
branch offset, 8-9 
deferred mode, 5-25 
mode, 5-24 

•RELEAS request, 9-74 
Releasing USR from memory, 9-57 
REL format, 6-1 
output file, 6-2 
switch, 6-23 
Relocatable, 1-2, 5-3 
code, 6-4.1 

expressions, 5-18, 8-4 
image file, 2-3 
image format (.REL), 2-3 
object module, 8-1 
values, 8-18 
Relocation, 8-4 
base, 2-29 
bias, 8-4, 8-17 
calculators, 8-18 
constant, 5-3 
directory, 7-14 
register commands, 8-17, 8-18 
registers, 8-6, L-l 
Relocation and Linking, 5-19 
.REMOV, N-9 


Removing, 

handlers from memory, 9-74 
logical assignments, 2-19 
terminated jobs, 2-22 
Rename function, 0-63 
Rename operation, 4-15 
•RENAME request, 9-75 
Reopen a channel, 0-64 
•REOPEN request, 9-77 
Repeat block, 5-73 
Repeat counts, 8-23 
Repeat subroutine, 0-107 
Replace switch, 7-5 
Replacement file, 4-8.1 
.REPT directive, 5-73 
Requests 

for data transfer, 9-14 
for file manipulation, 9-14 
for miscellaneous services, 9-14 
requiring the USR, 9-19 
Requests, programmed, 9-1 
Requests 

.CDFN, 9-26 
.CHAIN, 9-27 
•CHCOPY, 9-28 
.CLOSE, 9-30 
.CMKT, 9-31 
.CNTXSW, 9-32 
•CSIGEN, 9-33 
.CSISPC, 9-36 
.CSTAT, 9-41 
•DELETE, 9-42 
.DEVICE, 9-44 
.DSTATUS, 9-45 
.ENTER, 9-47 
.EXIT, 9-49 
.FETCH, 9-50 
.GTIM, 9-51 
.GTJB, 9-52 
.HERR, 9-53 
.HRESET, 9-55 
.LOCK, 9-56 
.LOOKUP, 9-58 
.MFPS, 9-21.1 
.MRKT, 9-60 
.MTPS, 9-21.1 
.MWAIT, 9-62 
.PRINT, 9-63 
.PROTECT, 9-64 
.PURGE, 9-65 
•QSET, 9-65 
.RCTRLO, 9-67 
.RCVD, 9-68 
.RCVDC, 9-69 
.RCVDW, 9-69 
.READ, 9-71 
.READC, 9-72 
.READW, 9-73 
.RELEAS, 9-74 
.RENAME, 9-75 
•REOPEN, 9-77 
.RSUM, 9-87 
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Requests (cont.) f 
.SAVESTATUS, 9-77 
.S DAT, 9-80 
.SDATC, 9-81 
.SDATW, 9-81 
.SERR, 9-53 
. SETTOP, 9-8 2 
.SFPA, 9-84 
.SPFUN, 9-85, H-13 
.SPND, 9-87 
.SRESET, 9-90 
.TLOCK, 9-91 
.TRPSET, 9-92 
.TTINR, 9-94 
.TTYIN, 9-93 
.TTYOUT, 9-95 
.TTOUTR, 9-95 
.TWAIT, 9-98 
.UNLOCK, 9-57 
.WAIT, 9-71, 9-99 
.WRITC, 9-101 
.WRITE, 9-100 
.WRITW, 9-102 

Reserving storage area, 5-16 
Resident monitor (RMON), 2-7.1, 

9- 7 

Resident overlay handler, 6-15 
Restarting ODT, clearing break¬ 
points, 8-2 
Restarting PIP, 4-1 
.RESTR, N-9 

Restrictions on expanding macros, 

10- 1 

RESUME subroutine, 0-108, 0-113 
Return 

from Interrupt Service, H-2 
to previous sequence, 8-9 
to monitor, CTRL C, 8-3 
Return path, 6-13 
Reusing bad blocks, 4-19 
Rewind, H-ll, H-12, 0-72 
Ring buffer I/O, H-6 
Root segment, 2-28, 6-10, 6-14, 
L-3 

Rotate/Shift Instructions, C-9 
Rounding numbers, 5-48 
Routine, Service Interrupt, H-2 
Routines, 1-3 

Routines, completion, 2-37, 2-38 
Routines used with FORTRAN, 0-4 
RSTS-11 DECtape, J-l 
.RSUM request, 9-87 
RSUME Command, 2-38 
RT-11 BATCH and RSX-11D BATCH 
differences, 12-52, 12-53 
$RT-11 command, 12-35, 12-38 
RT-11 directory-structured 
devices, 2-7 
RT-11 input, 12-2 
RT-11 mode, 12-38 
examples, 12-43 
switch, 12^4 


RT-11 services, O-ll, 0-12 
RT-11 System, 1-1 

data formats, file transfers, 
4-1 

DECtape control handler, J-5 
Foreground/Background monitor, 
1-7 

I/O transfers, 9-65 
librarian, 7-1 
memory maps 2-8, 2-9 
operating environments, 1-1 
Single-Job monitor, 1-7 
RUBOUT, 2-13, 3-3 
Rules and conventions, 12-11 
Rules for user-defined and macro 
symbols, 5-9 
$RUN command, 12-35 
RUN c ommand, 2-33 
Running, 

a FORTRAN program in the fore¬ 
ground, 0-5 
BATCH, 12-47 

RT-11 system programs, 12-39 
the program (ODT), 8-12 
Run-time area of memory, 6-10 
Run-time handler, 12-1, 12-45, 
12-50 

Run-time overlay handler, 6-12 
Run-time overlay handlers and 
tables, 6-1 

Run-time variables, 12-16 


Save buffer, 3-10 
SAVE command, 

(Monitor), 2-31 
(Editor), 3-10, 3-24 
Save image, 6-1, 6-2 
file (SAV), 6-5, 12-27 
format, 2-31, 6-21 
.SAVESTATUS request, 9-77 
.SBTTL directive, 5-34 
Schedule function, 0-66 
Scheduling requests, cancelling, 0-36 
Scheduling subroutines, 0-77 
SCOMP routine, 0-108 
SCOPY routine, 0-109 
.SCROL, N-10 

Scroller, 2-15, 3-29, N-2 
buffer, N-3 
logic, N-3 
.SDAT request, 9-80 
.SDATC request, 9-81 
.SDATW request, 9-81 
Search, 

algorithm (ODT), 8-24 
commands (EDIT), 3-4, 3-18, B-6 
effective address, 8-15 
for string, 0-48 
limit (ODT), 8-15 
word, 8-15 
Searches, 8-14, 8-24 
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SECNDS function, 0-110 
Segment boundaries, 4-18 
Send Data/Receive Data, 1-8 
Sentinel file, 4-4 
Separating and delimiting 
characters, 5-6 
Separator, 2-11 
$SEQUENCE command, 12-36 
Sequence numbers, 4-7 
Sequential-access devices, 2-7, 
9-45, H-13 

Sequential operations, H-9 
.SERR request, 9-53 
Services, 0-7 
Set Bottom Address, L-4 
SET command, 2-23 
options, 2-23 

Set Relocation Registers, L-4 
Setting the Editor to immediate 
mode, 3-30 

Setting up interrupt vectors, H-3 
.SETTOP request, 9-82 
.SET USR NOSWAP command, 9-84 
Seven-word status buffer, N-10 
•SFPA request, 9-84 
Sharing a location, 9-32 
Sharing system resources, 1-1 
Single absolute section, 5-54 
Single instruction, 
address, 8-14 
mode, 8-14 
Single-job 

monitor, 2-18, 3-30, 9-7 
operation, 1-1 
Single load module, 7-1 
Single operand instructions, C-8 
Size specification, 9-37 
Slash, 8-6 

Soft error recovery, 9-54 
Software, 

components, monitor, 2-7.1 
mode, H-6, H-13 
name register, N-7 
requirements (BATCH), 12-2 
Software Identification Numbers, 
xxii 

Solid state memory, 1-1 
Source compare (SRCCOM), 1-4, K-l 
error messages, K-5 
switches, K-2, B-19 
Source-Double Register, C-17 
Source, 

code, 1-2 

code, macro-free, 10-1 
field, 9-3 
lines, 5-2 
operand mode, 5-25 
program, 1-2, 5-2 
program format, 5-2 
register, C-15 

Spacing to the end of the tape, 
4-6 


Special characters, 5-64 
Special key commands, EDIT, 3-2 
Special function keys, 2-12, B-3 
CTRL A, 2-12 
CTRL B, 2-12 
CTRL C, 2-12 
CTRL E, 2-12 
CTRL F, 2-12 
CTRL 0, 2-13 
CTRL Q, 2-13 
CTRL S, 2-13 
CTRL U, 2-13 
CTRL Z, 2-13 
RUBOUT, 2-13 
Special functions, 0-72 
Special mode TT bit, 9-8 
Specification fields, 12-5 
switches, 12-7 
Specifier, 
address, M-2 
value, M-2, M-3 
Specifying, 

directory segments, 4-19 
extra words per directory 
entry, 4-18 

.SPFUN request, 9-85, H-13.2 
•SPND request, 9-87 
SRCCOM, see Source Compare 
.SRESET request, 9-90 
Stack, 9-50 
address, 6-21 
pointer, 6-21, 9-7 
size, changing, 2-36 
Standard end-of-file card, H-6 
.START, N-10 

Start address, 6-7, 9-7, H-3 
START Command, 2-34 
Start procedure, 2-1 
Starting and stopping the display 
processor, N-2 
Starting block number, 9-78 
.STAT, N-10 
Statement, 
format, 5-2 
terminator, 5-2 
Statements, 

assembly language, 5-2 
direct assignment, 5-10, 5-14 
BASIC/RT-11, F-l 
.ENDM, 5-74 
.ENDR, 5-74 
.MACRO, 5-2 

Status word, 9-45, H-l 
.STOP request, N-ll 
Stopping points, 1-3 
Storage device, 3-1 
String, BASIC/RT-11, F-5 
Strings (SYSLIB), 0-18 
concatenation, 0-24 
length, 0-97 
STRPAD routine, 0-111 
Subconditionals, 5-57 
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Subpicture tag data, N-13 
Subprogram summary, 0-7 - 0-14 
Subroutine, 

call instruction, N-18 
return, C-14 

SUBROUTINE subprograms, 0-3 
Subroutines, library functions and 
0-21 - 0-120 
SUBSTR routine, 0-112 
Subtract INTEGER*4 values, 0-95 
Summary, 

command, B-l 

graphics macro calls, N-21 
MACRO assembler, C-l 
programmed requests, 9-15 
switch, B-l 
SUSPEND command, 2-37 
Suspending program execution, 9-99 
0-82, 0-84, 0-101, 0-113 
SUSPND subroutine, 0-113 
Swapped region, 9-9 
Swapping, 9-56 
algorithm, 9-9 
routines, 0-5 
Switch description, 6-18 
Switch summary, B-l 
BATCH, B-l4 
CREF, C-24 
DUMP, B-l8 
FILEX, B-18 
Librarian, B-12 
Linker, B-ll 
MACRO/CREF, C-23 
PIP, B-9 
SRCCOM, B-l9 
Switches, 2-10 
CREF, 5-76, 5-78 
function control, 5-76, 5-77, 
C-23 

listing control, 5-76, C-23 
Macro, 5-76 
PIP, 4-2 

Switches (BATCH), 

command field, 12-3, 12-6 
specification field, 12-6 - 
12-8 

Symbol control, 5-54 
Symbol table, 5-33 
global, 6-1, 6-5 
macro, 5-9 
overflow, 6-23 
permanent, 5-9 
switch, 6-23 
user, 5-9 
user-defined, 5-3 
Symbol, value, 5-9 
Symbolic arguments, 5-37 
Symbols, 5-9 
entry, 6-5 
external, 5-10, 6-5 
global, 5-10, 5-55, 6-5, M-3 
internal, 5-10 
local, 5-12, 5-66 


Symbols (cont.), 
macro, 5-9 

multiply-defined, 5-13 
permanent, 5-9 
register, 5-11, 5-12 
user-defined, 5-3, 5-9 
Symbols and expressions, 5-5 
.SYNC and .NOSYN requests, N-ll 
.SYNCH, macro call, 9-22 
Synchronization, N-ll 
SYSLIB, 1-5, 9-1, 0-1 

calling subprograms, 0-3 
channel-oriented operations, 

0-17 

character-string functions, 

0-18 

completion routines, 0-15 

conventions, 0-2 

INTEGER*4 support functions, 

0-17 

library functions and subrou¬ 
tines, 0-21 - 0-120 
linking, 0-6 
restrictions, 0-2 
running in foreground, 0-5 
summary of subprograms, 0-7 - 0-14 
using with MACRO, 0-3 
SYSMAC.8K, 9-1, 10-1 
SYSMAC.SML, E-l, 9-1 
System, 

build operation, 2-3 
communication, 2-1 
communication area, 6-6, 9-7 
concepts, 9-5 
conventions, 2-3 
date, 9-11 

device, 2-1, 2-21, 2-34 
device scratch blocks, 9-49 
disk-usage efficiency, 4-12 
files, 4-10 

hardware components, 1-5, 1-6 

macros, 9-20 

macro library, D-l 

programs, 1-1 

software components, 1-3 

state, 9-21 

unit, 2-21 

System software components, 1-3 
ASEMBL, 1-4, 11-1 
BATCH, 1-5, 12-1 
CREF, 1-4, 5-78 
DUMP, 1-5, 1-1 
EDIT, 1-3, 3-1 
EXPAND, 1-4, 10-1 
FILEX, 1-4, J-l 
Librarian, 1-4, 7-1 
Linker, 1-4, 6-1 
MACRO, 1-3, 5-1 
ODT, 1-5, 8-1 
PATCH, 1-4, L-l 
PATCH0, 1-4, M-l 
PIP, 1-4, 4-1 
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System software components (cont.) 
SRCCOM, 1-4, K-l 
SYSLIB, 1-5, 0-1 
System subroutine library, see 
SYSLIB 


TAB character, 3-3, 5-2 
Table of 

breakpoints, 8-12, 8-13 
mode forms and codes, 5-25 
proceed command repeat counts, 
8-13 

Tag value, N-7 

Tagged subpicture file structure, 
N-18, N-20 

Temporary files, 4-23, 12-15 
listing, 12-4 
object, 12-4, 12-28 
Temporary linkage map, 12-4 
Temporary numeric control, 5-49 
Temporary radix control, 5-45 
Tentative entry, 9-47 
Tentative file, 9-13, 9-65 
Terminal, 

input request, 2-14 
interrupt, 8-24 
I/O control, 12-42 
Terminate search, 8-4 
Terminating BATCH, 12-52 
control statement, 12-2 
jobs on cards, 12-45 
Terminating directives, 5-50 
Terms, 5-17 
Testing patches, 2-28 
Text, 1-2 

blocks, 7-14 
buffer, 3-2, 3-21 
Editor, 3-1 
mode, 3-2, 3-20 
modification, 3-4 
modification commands, 3-20 
TIMASC subroutine, 0-114 
TIME command, 2-17 
Time conversion, internal to 
ASCII, 0-114 
Time-critical job, 1-7 
Time format, 0-17 
Time of day, 12-5, 0-29, 0-115 
Time of day, access to, 9-51 
Time interval, 9-60 
TIME subroutine, 0-115 
Timed Wait, 1-8 

Timer support functions, 0-10, 
0-11, 0-96, 0-110, 0-115 
Timing requests, 9-66 
.TITLE directive, 5-34 
.TLOCK request, 9-91 
Trace trap instruction, 8-21 
.TRACK completion routine, N-12 
.TRACK request, N-12 
Tracking object, N-2, N-12, N-19 
Trailing blank, 0-118 


Trailing delimiter, 5-43 
Transfer address, 6-7, 6-24 
Transfer, 

image mode, 4-9 
packed image, J-2 
word-for-word, J-2 
Transferring characters, 9-93 
Transferring files, 4-8, 4-11 
between RT-11 and DOS/BATCH 
(or RSTS), J-3 

to RT-11 from DECsystem-10, J-5 
Transferring memory, 2-31 
TRANSL routine, 0-116 
Transmitting data, 9-68 
TRAP addressing, EMT and, 5-27 
Trap instructions, 8-14, C-12 
Trap interception, 9-92 
TRIM routine, 0-118 
.TRPSET request, 9-92 
TT 

handler for console terminal, H-5 
printer interrupt, 8-25 
.TTYIN request, 9-93 
.TTINR request, 9-94 
.TTY0UT request, 9-95 
.TT0UTR request, 9-95 
Turning off user error interception 
9-54 

.TWAIT request, 9-98 

Two-volume compress, 4-19 

Type ahead, 2-14, H-5 

Types of programmed requests, 9-14 


UIC, User Identification Code, J-3 
default value, J-4 
Unary operators, 5-8, 5-45, 5-50 
Unconditional transfer of program 
control, 12-41 

Unit number (system device), 9-11 
Unique spelling of switches and 
keynames, 12-5 
•UNLNK, N-13 
UNLOAD command, 2-21 
.UNLOCK request, 9-57 
UNLOCK subroutine, 0-118 
Unnamed control section, 6-4 
Unrecoverable hardware/software 
error, 7-15 

Unresolved globals, 6-1 
Unsave command, 3-25 
Unused areas, 4-16 
Up-arrow construction, 5-63 
Up-arrow, 8-8 
prompt, H-5 
Update, 

number, 9-11 
switch, 7-9 

Updating cassette sequence number, 
4-7 

Upper-case characters, 0-80 
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Upper-/lower-case, 

commands, 3-27 
mode, 3-27 
terminal, 3-27 
Urgent messages, 9-63 
User command string, 3-1 
User-defined symbol, 5-3, 5-9 
table, 5-3 

User library searches, 6-16 
User program, 5-3 
protection, 9-34 

User Service Routine (USR), 2-7.1 
address, 2-32 
swapping, 2-27 

User switch commands and functions 
(LIBR), 7-2 

User-written device handlers, H-4 

User symbol table, 5-9 

Using, 

.ASECT Directives, H-3 
display editor, 3-29 
libraries, 6-15 
ODT with F/B jobs, 8-3 
overlays, 6-10 
.SETTOP, H-3 

the system macro library, 9-14 
the display file handler, N-16 
the wild-card construction, 4-1 
USR area, 9-11 

load address, 9-8 
USR 

access to (SYSLIB), 0-79 
ownership acquisition, 9-91 
swap bit, 9-7 
swapping, 9-9, 9-79 
unlocking, 0-118 
Utility commands, Editor, 3-4, 

3-24, B-7 

Utility program, PATCH, L-l 
Utility routines, 8-20 


VTHDLR, N-25 
VTLIB library, N-26 
VTMAC, N-27 


Wait for operator action, 12-5 
.WAIT request, 9-71, 9-99 
Warning messages, PIP, 4-25 
Wild card, 

construction, 4-10, 12-7, 12-16 
expansion, 4-10 
names, J-l 
Word, 

address, L-3 
count, H-9 

-for-word transfer, J-2 
search, 8-15, 8-24 
status, H-l 
WORD command, M-2 
Word count, variable number, 9-68 
•WORD directive, 5-39 
Words, allocating, 2-36 
.WRITC request, 9-101 
Write, 

character string, 0-103 
end-of-file, H-ll 
file gap, H-13 
with extended gap, H-12 
Write command, 3-13 
•WRITE request, 9-100 
WRITE-ENABLE, 12-5 
Write function, 0-84 
WRITE-LOCK, 12-5 
•WRITW request, 9-102 


..VI.. macro call, 9-24 
..V2.. macro call, 9-24 
Value specifier, M-2, M-3 
Variables, 

character string, 0-19 
INTEGER*4, 0-17 
RT-11 mode, 12-40 
run-time, 12-16 
Vector addresses, 9-6 
Verify command, 3-15 
VERIFY routine, 0-119 
Version, 

history, xxii 

number message, 4-21, L-l 

switch, 4-21 

Vertical formatting, 5-5 
VT-11 Display processor, 1-3, 
2-15 

VTBASE, N-24 
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DEC-ll-ORUGA-C-D, DN1, DN2 


o 

READER'S COMMENTS 


NOTE: This form is for document comments only. Problems 

with software should be reported on a Software 
Problem Report (SPR) form. 


Did you find errors in this manual? If so, specify by page. 



Did you find this manual understandable, usable, and well-organized? 
Please make suggestions for improvement. 


V) 



d Is there sufficient documentation on associated system programs 

v required for use of the software described in this manual? If not, 

g what material is missing and where should it be placed? 

Q_ _—.... 




Please indicate the type of user/reader that you most nearly represent. 

| Assembly language programmer 
| | Higher-level language programmer 

□ Occasional programmer (experienced) 

| | User with little programming experience 
| | Student programmer 

□ Non-programmer interested in computer concepts and capabilities 

Name _ Date_ 

Organization_ 

Street___ 

City-State_Zip Code___ 

or 

Country 

If you require a written reply, please check here. □ 
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